Skip to main content

​
Self-Custodial Model

Circuit never takes custody of user funds. Private keys live in a secure enclave (KMS) completely separate from agent code. Agents can only request transactions — signing happens outside the agent sandbox. Agent code never sees private keys, users can export their wallet at any time, and all transactions are visible onchain.

​
Wallet Types

Agents declare their required wallet type in circuit.toml:
  • "ethereum" — EVM-compatible chains (Ethereum, Polygon, Arbitrum, Base, etc.)
  • "solana" — Solana
An agent can only run on wallets matching its walletType.

​
Starting Asset

Every agent defines a startingAsset in circuit.toml — the token a user must hold to start a session: 
[startingAsset]
network = "ethereum:137"
address = "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb"  # pUSD on Polygon
minimumAmount = "1000000"  # 1 pUSD (6 decimals)
  • network — The chain where the asset lives (Network Identifiers)
  • address — Token contract address. For native tokens: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" (EVM) or "11111111111111111111111111111111" (Solana)
  • minimumAmount — Minimum balance required in raw units (wei, lamports, etc.). Hyperliquid hypercore:perp + USDC uses 8 decimal places in Circuit (not EVM USDC’s 6); see Hyperliquid.

​
How Allocation Works

When a user starts a session:
  1. Circuit verifies the user holds at least minimumAmount of the starting asset
  2. The specified amount is allocated to the agent session
  3. The agent receives these allocations as agent.portfolio
Hyperliquid agents allocate the same way: you allocate a portion of the wallet’s Hyperliquid USDC collateral to the session, and multiple Hyperliquid agents can share one wallet — each draws from the unallocated remainder. Because a shared wallet nets positions at the account level, agents on the same wallet share liquidation risk, so size and monitor positions accordingly.

​
Positions

agent.portfolio is a field captured at execution start (no await, no success/data wrapper):
  • agent.portfolio.balances — fungible inventory the session holds outright: cash, spot tokens, staking, and Polymarket pUSD cash.
  • agent.portfolio.positions — open market exposures: Hyperliquid perps (signed sizes) and Polymarket outcome-token positions (enriched with polymarketMetadata). Tell them apart by whether polymarketMetadata is present.
Important: agent.portfolio is captured at the start of each run and does not refresh mid-cycle. After executing transactions, track the changes you make in Memory if you need updated state within the same run. Hyperliquid note: For live Hyperliquid state, use agent.platforms.hyperliquid.balances() and agent.platforms.hyperliquid.positions() — these read directly from the clearinghouse. See Hyperliquid.

​
Units

  • All amounts are strings in smallest units (wei for EVM, lamports for Solana)
  • Keep amounts as strings to preserve precision for large values
  • Hyperliquid exception: Amounts are formatted values (e.g., "1.5" for $1.50 USDC), not raw units

​
See Also