agent.allocation is the session’s allocation and attribution snapshot, read when the invocation starts, refreshed before each money write resolves and as the execution model describes; it is not shared-wallet holdings or a signing boundary. If a refresh fails, reading it throws that failure. 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 (negative for a short or a borrowed position), priceUsd, entryPriceUsd, valueUsd, unrealizedPnlUsd and pricedAt, which is set whenever priceUsd is. quantity is whole tokens, the unit swap and transfer amounts take. token is fungible inventory, supplied and borrowed are lending, vault and staking positions, perp is perpetual exposure on a perp venue, and prediction is a Polymarket outcome-token position; each adds its own fields at the top level of the row. A token row adds availableQuantity, what a new order can spend: quantity less the margin the session’s open perps hold in that collateral and their unrealized losses, never below 0.
supplied (value supplied to a lending protocol, vault or stake, including collateral posted to secure loans) and borrowed (debt owed to a lending protocol) add protocol (Circuit’s id for the protocol, such as aave or morpho, or null for a vault or stake pool Circuit knows no protocol for), market (the market agent.lending names: the Aave or Spark pool, the Aave V4 <spoke>/<reserveId>, the Euler vault, the Morpho market id or the Kamino lending market; a liquidity position names its pool (the pool contract on Uniswap v3, the poolId on Uniswap v4); a vault or stake names its own contract), underlying, underlyingQuantity and apy. A liquidity position is several supplied rows sharing its position, the value agent.liquidity takes to add or remove (null on every other supplied row); select it by position, never by parsing asset, and its apy is null. Its rows also share range, { lowerPercent, upperPercent, inRange }: the position’s live span as percent offsets from the pool’s current price, the coordinate open takes, and whether that price is inside it; range is null on every other supplied row and when the read failed, which errors names. A Metric position, on the networks whose protocolDeployments list metric, is <pool>/<salt> with two rows with protocol metric per held bin, one per pool token, whose asset is <network>:claim:metric:<pool>/<salt>/<bin>/<token>:supply: quantity is the position’s shares in that bin at 18 decimals, and underlyingQuantity that token’s part of the bin’s balance, fees included. A Uniswap v3 or v4 position is its position manager NFT id with four rows with protocol uniswap-v3 or uniswap-v4, principal and uncollected trading fees per pool token, whose asset is <network>:claim:<protocol>:<tokenId>/<0|1>/<principal|fees>:supply: each quantity is the session’s share of the NFT’s liquidity at zero decimals, moved only by the session’s own receipts, and underlyingQuantity that currency’s live principal or fees for it. quantity is in the position’s native unit (the token’s balance, which grows with interest for a lending supply, debt or liquid stake, or the protocol’s shares or collateral units for a position without a token) and priceUsd is per native unit, so valueUsd is quantity times priceUsd as for every kind. A supplied row also carries securesLoans, true when the protocol counts it as collateral for loans in its lending account; posted collateral earns nothing, so its apy is 0. A borrowed row’s quantity and valueUsd are negative. underlyingQuantity is quantity in whole units of underlying: the same number for a token whose balance grows with interest, else quantity at Circuit’s latest share rate; apy is the current annual rate as a fraction (0.05 is 5%). A position without a token has the Circuit position key ending in :collateral, :supply or :borrow as its asset; a token position’s asset is its contract. A borrowed row also carries loanToValue (the wallet’s whole lending account, the market, pool or obligation the protocol liquidates together, including other sessions’ and manual positions there: its loans over the collateral securing them, both at Circuit’s marks, which can differ slightly from the protocol’s oracle), liquidationLoanToValue (the securing collateral’s liquidation thresholds averaged by collateral value) and healthFactor (their quotient; liquidatable below 1); both are null when the protocol publishes no liquidation threshold Circuit reads. A supplied or borrowed row’s quantity, its USD fields and underlyingQuantity are null when Circuit holds no current share rate for the position, and its errors says why; it is empty otherwise. Read these facts here rather than from chain reads.
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. Holdings use operation asset identities.
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. These four USD fields and the ratio fields carry at most 18 decimal places, truncated toward zero, while quantity stays exact at its asset’s own decimals, which can exceed 18.
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. A prediction holding’s acceptingOrders is false once Polymarket stops taking orders on its market, including while resolution is pending: skip quoting or selling it and redeem it once isRedeemable.
Each session is its own virtual wallet: holdings change only through its allocations, its own fills and fees, realized P&L against its own entry, funding on its own perpetuals and interest on its own balances. Deposits, withdrawals, manual trades and other sessions never move them, so a holding can go negative or oppose the account’s live position. A Hyperliquid account liquidation shrinks the sessions holding the liquidated side in proportion to their holdings, and a Papertrade position closed outside its session counts as the opening session’s own. Close a session position with a plain opposite order, and a Papertrade position by its holding’s positionId.
Allocation guides honest but fallible agents and attributes effects; the transaction SDK adds no allocation enforcement. Multiple sessions of different agents share wallet signing authority and funds, and Hyperliquid liquidation risk, since positions net at the account; the same agent cannot have two active sessions on one wallet. Size typed SDK and raw-wallet actions from the session allocation. Ask Circuit and reviewed operations can use the full selected wallet or venue account, overriding attribution. Every surface shares the signer and transaction lifecycle and enforces its request, permit, policy and live checks.