Positions

​

Reading the Allocation

type VirtualAllocation = {
  balances: AllocationBalance[];   // fungible inventory the agent holds outright
  positions: AllocationPosition[]; // open market exposures (HL perps + Polymarket positions)
}

• balances - fungible inventory the session holds outright: cash, spot tokens, staking positions, and Polymarket pUSD cash.
• positions - open market exposures: Hyperliquid perpetuals (signed sizes) and Polymarket outcome-token positions. The two are distinguished by whether polymarketMetadata is present (present = Polymarket position; absent/None = Hyperliquid perp).

​

AllocationBalance Fields

• network (string): Network identifier (e.g., “ethereum:137”)
• assetKey (string): Canonical asset key
• tokenAddress (string): Token contract address
• tokenId (string | null): Token ID for NFTs/ERC1155 (null for fungible tokens)
• symbol (string | null): Token symbol
• decimals (number): Token decimals
• amountRaw (string): Quantity held in raw base units
• marketValueUsd (string | null): Current market value in USD
• hyperliquidMetadata ({ collateral: true }, optional): present only on the Hyperliquid perp-margin USDC balance (deployable collateral, total basis - includes locked margin, excludes unrealized PnL; equity = collateral + Σ positions’ unrealizedPnlUsd, free margin ≈ equity − Σ marginUsed). Absent on everything else (EVM/Solana tokens, HL spot/staking) - read network to distinguish those.

​

AllocationPosition Fields

• network (string): Network identifier
• assetKey (string): Canonical asset key
• coin (string): For HL perps, the perp coin (e.g., “BTC”); for Polymarket positions, the outcome label (e.g., “Yes”)
• size (string): For HL perps, the signed position size - long > 0, short < 0; for Polymarket positions, the shares held (decimal string)
• averageEntryPrice (string | null): Average entry price
• markPriceUsd (string | null): Current mark price in USD (Hyperliquid perp mark; Polymarket share mark for valuation)
• unrealizedPnlUsd (string | null): Unrealized PnL in USD
• polymarketMetadata (object, optional): Enriched Polymarket data - present only for Polymarket positions; absent/None for Hyperliquid perps. Fields:
  • question (string): Market question text
  • outcome (string): Outcome name (e.g., “Yes”, “No”)
  • marketValueUsd (string): Position value in USD
  • priceUsd (string): Current price per share
  • averagePriceUsd (string): Average entry price
  • pnlUsd (string): Profit/loss in USD
  • pnlPercent (string): Profit/loss percentage
  • pnlRealizedUsd (string): Realized PnL in USD
  • pnlRealizedPercent (string): Realized PnL percentage
  • isRedeemable (boolean): Whether the position can be redeemed
  • isNegativeRisk (boolean): Whether this is a negative risk market
  • imageUrl (string): Market image URL
  • endDate (string): Market end date
  • contractAddress (string): Polymarket contract address
  • tokenId (string | null): Outcome token ID
  • decimals (number): Token decimals
  • conditionId (string): Market condition ID
  • formattedShares (string): Human-readable share count
  • shares (string): Raw share count
  • initialValue (string): Initial position value

​

Example

allocation = agent.allocation

for balance in allocation.balances:
    agent.log(f"Balance: {balance.symbol or balance.token_address}")
    agent.log(f"  Amount: {balance.amount_raw} (raw)")
    agent.log(f"  Value: ${balance.market_value_usd}")

for position in allocation.positions:
    if position.polymarket_metadata:
        # Polymarket outcome-token position
        pm = position.polymarket_metadata
        agent.log(f"Polymarket: {pm.question}")
        agent.log(f"  Outcome: {pm.outcome}")
        agent.log(f"  Shares: {pm.formatted_shares}")
        agent.log(f"  Value: ${pm.market_value_usd}")
        agent.log(f"  PNL: ${pm.pnl_usd} ({pm.pnl_percent}%)")
    else:
        # Hyperliquid perp
        agent.log(f"Perp {position.coin}: size {position.size}")
        agent.log(f"  Unrealized PnL: ${position.unrealized_pnl_usd}")

const allocation = agent.allocation;

for (const balance of allocation.balances) {
  await agent.log(`Balance: ${balance.symbol ?? balance.tokenAddress}`);
  await agent.log(`  Amount: ${balance.amountRaw} (raw)`);
  await agent.log(`  Value: $${balance.marketValueUsd}`);
}

for (const position of allocation.positions) {
  if (position.polymarketMetadata) {
    // Polymarket outcome-token position
    const pm = position.polymarketMetadata;
    await agent.log(`Polymarket: ${pm.question}`);
    await agent.log(`  Outcome: ${pm.outcome}`);
    await agent.log(`  Shares: ${pm.formattedShares}`);
    await agent.log(`  Value: $${pm.marketValueUsd}`);
    await agent.log(`  PNL: $${pm.pnlUsd} (${pm.pnlPercent}%)`);
  } else {
    // Hyperliquid perp
    await agent.log(`Perp ${position.coin}: size ${position.size}`);
    await agent.log(`  Unrealized PnL: $${position.unrealizedPnlUsd}`);
  }
}

​

Notes

• The snapshot does not mutate during an invocation. Track effects in local variables when a later step depends on an earlier action; the next trigger receives a fresh snapshot containing committed top-ups and transaction effects.
• Amounts (amountRaw) and sizes are strings to preserve precision for large numbers.
• Polymarket positions always include enriched polymarketMetadata (question, outcome, PNL, etc.). It is absent/None for Hyperliquid perps, so its presence is how you tell the two kinds of position apart.
• Both Hyperliquid perps and Polymarket positions appear in allocation.positions. For live Hyperliquid state, read directly from the platform methods (see below).

​

See Also

• Wallets & Asset Allocation - How assets are allocated to sessions
• Memory - Persist strategy state across runs, never portfolio mirrors
• Hyperliquid - Hyperliquid agents use platform-specific balance methods for live state