Skip to main content
Use positions to check what assets are available to your agent and verify balances after transactions. Most agents read currentPositions at the start of each run to decide what to do.

​
Current Positions

agent.currentPositions contains assets allocated at the start of execution. Each position includes:
  • network (string): Network identifier (e.g., “ethereum:137”)
  • assetAddress (string): Token contract address
  • tokenId (string | null): Token ID for NFTs/ERC1155 (null for fungible tokens)
  • avgUnitCost (string): Average unit cost in USD. Currently returns "0" — cost basis tracking will be enabled in a future release.
  • currentQty (string): Current quantity held (raw amount)
Note: currentPositions reflects balances at execution start. After transactions, use getCurrentPositions() for updated balances.

​
Get Current Positions

Get live positions with updated balances. Indexing speed varies by chain, so updated positions may not appear immediately after transactions are submitted. For agents that need position updates under 5-10 seconds, it is recommended to track position changes in memory instead. 
def get_current_positions() -> CurrentPositionsResponse
Response:
  • success (boolean): Whether the operation succeeded
  • data.hasPendingTxs (boolean): Whether there are pending transactions
  • data.positions (array): Array of current positions
  • error (string | null): Error message (on failure)
Position Fields:
  • network (string): Network identifier
  • assetAddress (string): Token contract address
  • tokenId (string | null): Token ID for NFTs/ERC1155
  • avgUnitCost (string): Average unit cost in USD
  • currentQty (string): Current quantity held (raw amount)
  • polymarketMetadata (object | null): Enriched Polymarket position data (if applicable)
    • 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 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: 
result = agent.get_current_positions()
if result.success and result.data:
    if result.data.hasPendingTxs:
        agent.log("Warning: Pending transactions may affect balances")

    for position in result.data.positions:
        agent.log(f"Position: {position.assetAddress}")
        agent.log(f"  Quantity: {position.currentQty}")
        agent.log(f"  Avg Cost: ${position.avgUnitCost}")

        if position.polymarketMetadata:
            pm = position.polymarketMetadata
            agent.log(f"  Market: {pm.question}")
            agent.log(f"  Outcome: {pm.outcome}")
            agent.log(f"  Value: ${pm.valueUsd}")
            agent.log(f"  PNL: ${pm.pnlUsd} ({pm.pnlPercent}%)")

​
Handling Pending Transactions

If hasPendingTxs is true, wait until it’s false before relying on balances, as this indicates not all transactions have been indexed. Indexing speed varies by chain. For critical time-sensitive logic, track position changes in memory instead: 
import time

retry_count = 0
max_retries = 10

while retry_count < max_retries:
    positions = agent.get_current_positions()
    if positions.success and positions.data:
        if positions.data.hasPendingTxs:
            agent.log("Pending transactions detected, retrying...", debug=True)
            retry_count += 1
            time.sleep(1)
        else:
            break

​
Notes

  • currentPositions is provided at execution start. Use getCurrentPositions() for live balances.
  • Quantities are strings to preserve precision for large numbers.
  • Polymarket positions include enriched metadata (question, outcome, PNL, etc.).
  • Check hasPendingTxs before relying on balance data after transactions.
  • For tracking position changes within an execution cycle, consider using Memory to store deltas instead of polling getCurrentPositions() repeatedly.

​
See Also