walletVmFamily requires a matching EVM or Solana wallet. Account uses declare configuration independently of startingAsset.
Allocation lifecycle
Start assigns the user’s exact starting-asset quantity;minimumAmountRaw supplies the default. Start and Top-up read existing unallocated holdings live under the allocation lock and commit only the reviewed quantity. Acquire funds through Terminal first. A zero target starts empty without a balance read, while account readiness still applies.
Hosted allocations live in PostgreSQL; embedded allocations live in .circuit/session.json, with observed operation facts in the embedded engine database at .circuit/engine. Each invocation receives a fresh agent.allocation from starting inventory and observed effects. Its snapshot is fixed for that invocation; track dependent effects locally.
Allocation Is Coordination, Not Custody
Allocation guides honest but fallible agents and attributes effects; the transaction SDK adds no budget enforcement. Multiple sessions share wallet signing authority and funds, and Hyperliquid liquidation risk. Size typed SDK and raw-wallet actions from the session allocation. Terminal and reviewed operations can use the full selected account, overriding attribution. Every surface shares the signer and transaction lifecycle and enforces its request, permit, policy and live checks.Allocation snapshot and units
allocation.holdings contains one row per holding, discriminated by kind: token is fungible inventory, perp is Hyperliquid exposure and prediction is outcome shares. Every kind carries quantity, priceUsd, entryPriceUsd, valueUsd, unrealizedPnlUsd and pricedAt; token adds amountRaw, and perp and prediction each add their own venue fields at the top level. Existing perp allocations pin direction and venue entry price; shorts have negative quantity, and collateral is separately assigned.
Hyperliquid tokens retain exact units. A perp holding’s margin figures use its collateralToken, while priceUsd, entryPriceUsd, valueUsd and unrealizedPnlUsd are USD on every kind. An unknown price or entry basis stays null; never substitute zero. Venue capacity requires live reads. Kraken amounts use amountRaw and decimals; inspect live open orders for committed inventory. Credential-wide balances do not establish session ownership.
Use smallest-unit strings, bigint, decimalToBaseUnits and baseUnitsToDecimal onchain; use exact decimal strings for venue quantities. The venue references own units and exit rules.