Positions

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.

import type { VirtualAllocation } from "circuit:sdk";

const allocation: VirtualAllocation = agent.allocation;

balances contains fungible inventory; size comes from amountRaw, not display USD. Every balance and position names its asset: the identity that network’s operations take, unchanged. positions is a closed union narrowed on network: hypercore positions carry signed size and Hyperliquid metadata, and ethereum:137 positions carry shares and Polymarket metadata.

for (const balance of agent.allocation.balances) {
  await agent.log(`${balance.network} ${balance.asset}: ${balance.amountRaw}`);
}
for (const position of agent.allocation.positions) {
  if (position.network === "ethereum:137") {
    await agent.log(`Polymarket ${position.outcome}: ${position.asset}`);
  } else {
    await agent.log(`Perp ${position.asset}: size ${position.size}`);
  }
}

asset is the string that network’s operations take: a contract address or mint for transfers and swaps; on hypercore a balance’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() (HYPE/USDC); KRAKEN:XBT matches a Kraken catalog base or quote; a position’s asset goes into orders and triggers. tokenId is null unless the balance is an ERC-1155 id. Circuit asset keys are not exposed. The snapshot is immutable for one invocation. Track dependent effects locally; the next trigger receives committed changes. Amounts and sizes remain exact strings. See wallets and allocations.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced