Agent Context

AgentContext is passed to your run and unwind functions. It has session data and all SDK methods.

Session Data

session_id (Python) / sessionId (TypeScript) (number): Unique session identifier
session_wallet_address (Python) / sessionWalletAddress (TypeScript) (string): Wallet address for this session
execution_mode (Python) / executionMode (TypeScript) (string): "auto" or "manual"
settings (object): Resolved settings (defaults merged with session overrides)

SDK Methods

Python
TypeScript

log(): Send messages to users and log locally
memory: Key-value storage (shared=True for shared scope, omit for session)
platforms: Platform integrations (Polymarket, Hyperliquid)
swap: Cross-chain swap operations
sign_and_send(): Sign and broadcast transactions
sign_message(): Sign messages (EVM only)
transactions(): Get transaction history
clear_suggested_transactions(): Clear pending suggestions (manual mode)
allocation: The session’s virtual allocation snapshot at invocation start

log(): Send messages to users and log locally
memory: Key-value storage ({ shared: true } for shared scope, omit for session)
platforms: Platform integrations (Polymarket, Hyperliquid)
swap: Cross-chain swap operations
signAndSend(): Sign and broadcast transactions
signMessage(): Sign messages (EVM only)
transactions(): Get transaction history
clearSuggestedTransactions(): Clear pending suggestions (manual mode)
allocation: The session’s virtual allocation snapshot at invocation start

Basic Usage

def run(agent: AgentContext) -> None:
    agent.log(f"Session: {agent.session_id}")
    agent.log(f"Wallet: {agent.session_wallet_address}")
    allocation = agent.allocation
    agent.log(f"Balances: {len(allocation.balances)}")

async function run(agent: AgentContext): Promise<void> {
  await agent.log(`Session: ${agent.sessionId}`);
  await agent.log(`Wallet: ${agent.sessionWalletAddress}`);
  const allocation = agent.allocation;
  await agent.log(`Balances: ${allocation.balances.length}`);
}

Virtual allocation

agent.allocation is a field in both languages and has no success/data wrapper. It remains fixed for the invocation; the next trigger receives a newly constructed context with committed top-ups and transaction effects. See Positions for full details.

allocation = agent.allocation
for balance in allocation.balances:
    agent.log(f"{balance.symbol}: {balance.amount_raw} (raw)")
for position in allocation.positions:
    kind = "Polymarket" if position.polymarket_metadata else "Perp"
    agent.log(f"{kind} {position.coin}: size {position.size}")

const allocation = agent.allocation;
for (const balance of allocation.balances) {
  await agent.log(`${balance.symbol}: ${balance.amountRaw} (raw)`);
}
for (const position of allocation.positions) {
  const kind = position.polymarketMetadata ? "Polymarket" : "Perp";
  await agent.log(`${kind} ${position.coin}: size ${position.size}`);
}

Assets whose balance could not be verified

allocation.unreadable_assets (Python) / allocation.unreadableAssets (TypeScript) is normally empty. A key appears there when its contract refused the balance read — most often a token airdropped into the wallet whose balanceOf reverts, which nobody asked for and nobody can read. Such a key is left out of balances rather than carried at a stale quantity, because a balance that cannot be verified must never sit inside a spend cap. Everything else in the allocation is complete and spendable, so most agents can ignore the list entirely; an operation that names an unreadable key fails closed on its own.

for asset in agent.allocation.unreadable_assets:
    agent.log(f"Balance unavailable for {asset.asset_key} on {asset.network}")

for (const asset of agent.allocation.unreadableAssets) {
  await agent.log(`Balance unavailable for ${asset.assetKey} on ${asset.network}`);
}

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Session Data

SDK Methods

Basic Usage

Virtual allocation

Assets whose balance could not be verified

See Also

​Session Data

​SDK Methods

​Basic Usage

​Virtual allocation

​Assets whose balance could not be verified

​See Also

Session Data

SDK Methods

Basic Usage

Virtual allocation

Assets whose balance could not be verified

See Also