Architecture

System overview

The CLI coordinates five main components:

Smart wallet

The agent does not sign transactions with a raw private key. Instead, it operates through a Sequence Smart Wallet, an ERC-4337 account abstraction wallet that uses session-based permissions.

Key properties:

• Session-scoped: Permissions are bound to a time window and spending limits
• Gasless: Transaction fees are paid in ERC-20 tokens (USDC.e), not native POL
• Permission-gated: Every contract call is constrained by permissions set at wallet creation
• Recoverable: Backed by a passkey or session keypair

Session creation

When you create a wallet, the CLI opens a browser-based Connector UI at agentconnect.polygon.technology. The Connector authenticates you, creates the wallet and session keys, then sends the encrypted session back to the CLI.

The session is encrypted end-to-end. Only the CLI can decrypt it. The callback uses a Cloudflare Quick Tunnel by default. If the tunnel isn't available, the Connector displays the encrypted session for manual paste.

Session permissions

Spending limits and contract whitelists are set at wallet creation time and enforced at the smart contract level:

?nativeLimit=0.5        → Max POL per session
&usdcLimit=50           → Max USDC.e per session (default: 50)
&usdtLimit=100          → Max USDT per session
&tokenLimits=DAI:10     → Per-token custom limits (repeatable)
&contracts=0x8004...    → Whitelisted contract addresses (repeatable)

ERC-8004 registry contracts are always whitelisted automatically.

Transaction execution

All onchain writes go through a single function, runDappClientTx():

If the session has expired, the transaction is rejected before any network call is made.

Local EOA

The local EOA is a standard Ethereum wallet stored locally, encrypted with AES-256-GCM. It serves three purposes:

• Infrastructure authentication: Sequence project creation uses an EIP-712 proof tied to this address
• x402 payments: The EOA signs HTTP payment headers (servers verify a stable from address)
• Registry interactions: Onchain identity and reputation calls

During setup, the CLI creates the EOA, authenticates to Sequence Builder, provisions a project, and stores the encrypted key alongside the access credentials.

Trails: onchain orchestration

Trails is the orchestration layer for swaps, cross-chain bridging, and DeFi deposits (Aave, Morpho). The CLI interacts with Trails through the @0xtrails/api client.

Swap flow

Swaps use an intent-based model: the CLI requests a quote, commits to it, deposits tokens, then waits for settlement.

The depositTransaction from the quote is a pre-built { to, data, value } object. The CLI passes it directly to runDappClientTx() without ABI encoding.

Fund widget

The fund command generates a pre-filled URL to the Trails funding widget. It doesn't execute a transaction. You open the URL in a browser to complete a fiat onramp or cross-chain deposit.

ERC-8004: onchain agent identity

ERC-8004 is a standard for registering AI agents as persistent onchain identities. Registration mints an ERC-721 NFT to the agent's wallet address, giving it a permanent, verifiable ID. Reputation is tracked in a separate registry contract.

• Identity Registry: Mints the agent's NFT. The token ID is the permanent identifier, readable by any contract or offchain service.
• Reputation Registry: Stores feedback scores submitted by any address. Scores are permissionless to read.

x402: HTTP micropayments

x402 extends HTTP with a payment flow: a server responds with 402 Payment Required, and the client pays to gain access. The CLI handles the full client-side flow automatically.

How funding works: the smart wallet transfers the exact payment amount to the local EOA on demand. The EOA then signs the payment header. The EOA doesn't need a pre-existing balance. It's funded per-request from the smart wallet.

The CLI supports two signing methods, depending on what the server requires:

Environment variables