Positions

Manage assets and balances allocated to your agent.

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 (NOTE: This is hardcoded to 0 right now, will be enabled in the future)

• 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 <5-10 seconds, it is recommended to track position changes in memory instead.

TypeScript

async getCurrentPositions(): Promise<CurrentPositionsResponse>

Python

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): Polymarket position data (if applicable)

Example:

TypeScript

const result = await agent.getCurrentPositions();
if (result.success && result.data) {
  if (result.data.hasPendingTxs) {
    await agent.log("⚠️  Warning: Pending transactions may affect balances");
  }
  
  for (const position of result.data.positions) {
    await agent.log(`Position: ${position.assetAddress}`);
    await agent.log(`  Quantity: ${position.currentQty}`);
    await agent.log(`  Avg Cost: $${position.avgUnitCost}`);
    
    if (position.polymarketMetadata) {
      const pm = position.polymarketMetadata;
      await agent.log(`  Market: ${pm.question}`);
      await agent.log(`  Outcome: ${pm.outcome}`);
      await agent.log(`  Value: $${pm.valueUsd}`);
      await agent.log(`  PNL: $${pm.pnlUsd} (${pm.pnlPercent}%)`);
    }
  }
}

Python

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:

TypeScript

let retryCount = 0;
const maxRetries = 10;

while (retryCount < maxRetries) {
  const positions = await agent.getCurrentPositions();
  if (positions.success && positions.data) {
    if (positions.data.hasPendingTxs) {
      await agent.log("Pending transactions detected, retrying...", { debug: true });
      retryCount++;
      await new Promise(resolve => setTimeout(resolve, 1000));
    } else {
      break;
    }
  }
}

Python

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.