Skip to main content
Use the portfolio to check what assets are available to your agent. Most agents read agent.portfolio at the start of each run to decide what to do.

​
The Portfolio Field

agent.portfolio is a field (not a method) populated at the start of each execution. There is no await, no success/data wrapper — read it directly. It is always present and always Polymarket-enriched. 
portfolio: {
  balances: SessionBalance[];   // fungible inventory the agent holds outright
  positions: SessionPosition[]; // 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).
Python uses the same field names: agent.portfolio.balances, agent.portfolio.positions.

​
SessionBalance 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
  • valueUsd (string | null): Current marked value in USD
  • assetClass ("cash" | "spot" | "perp" | "staking"): What kind of holding this is
Polymarket pUSD cash appears here like any other cash balance. Polymarket outcome-token positions live in positions (see below), not in balances.

​
SessionPosition Fields

Open market exposures — both Hyperliquid perpetuals and Polymarket outcome-token positions. Distinguish the two by whether polymarketMetadata is present.
  • 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
  • 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”)
    • valueUsd (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

portfolio = agent.portfolio

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

for position in portfolio.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.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}")

​
Notes

  • agent.portfolio is captured at execution start. After transactions, it does not refresh within the same run — track changes you make in Memory if you need updated state mid-cycle.
  • 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 portfolio.positions. For live Hyperliquid state, read directly from the platform methods (see below).

​
See Also