How to connect an AI agent to a Web3 wallet (2026 guide)

The five-layer build order

Most tutorials begin with a private key in an environment variable. This one never takes that step. An agent that holds real money is five decisions stacked on each other, and each one is a separate entity in Agentic Finance Graph.

Our definition of agentic finance adds intent above and evidence below, but these five are the ones you wire yourself. The recurring question is the last column. An on-chain module, a TEE, or an API gateway counts as enforcement. A sentence in the system prompt does not.

Step 1 — Identity: an address first, a passport second

A wallet address is the cheapest identity in computing: milliseconds to create, no KYC at the protocol layer, able to sign. Create it inside a signer the model cannot reach — a TEE-backed wallet service or a hardware-approval path. The address is the agent. The key never has to be.

ERC-8004 registration is optional and comes second. The registry issues a passport, not a pulse: when Token Dispatch checked registrations in July 2026, 2.24 percent exposed a working service. Registrations are not agents. If you do register, publish the wallet under the agentWallet metadata key so indexers can bind identity to balance; our binder ranks that key first, the registration file second, and the owner address a distant third. See the ERC-8004 brief and the L0–L9 liveness ladder.

Step 2 — Choose the wallet kit by custody model, not by logo

Every kit answers two questions differently: who holds the key, and where the spend policy is enforced. The table records what vendors document as of 2026-09-04. We did not probe each product's endpoints for this guide; rows marked vendor claim are exactly that.

Two rules for choosing. Prefer policy enforced where the model cannot reach it: a chain module or a TEE beats an API flag, and an API flag beats a prompt. Prefer a wallet that keeps its address when policy changes: EIP-7702 does, ERC-4337 does not, and a treasury that changes address every quarter is hard to audit. The provider comparison scores each kit on custody, enforcement location, chains, and last live check.

Step 3 — Delegate the account, then issue a valet key

The minimal code path: scaffold an agent with a hosted wallet, add the x402 client packages, and pin your versions — the meta-packages move quickly.

# 1. Agent scaffold with a CDP wallet (Coinbase AgentKit)
npm create onchain-agent@latest

# 2. x402 client, EVM scheme, and the MCP adapter — pin versions
npm install @x402/core @x402/evm @x402/mcp

Now delegate. EIP-7702 has been live since Pectra on 7 May 2025. A type-0x04 transaction carries a signed authorization tuple; afterwards the account code is a 23-byte pointer, 0xef0100 followed by the implementation address. The account keeps its address, balance and history, and the EVM runs the implementation in the EOA's own context. Anyone may submit that transaction, so a sponsor can pay the gas — which is why the agent wallet can stay USDC-only from day one. Coinbase sponsors delegations on Base, Arbitrum, Ethereum, Optimism and Polygon; once the status reads COMPLETED, UserOperations go to the same address. Mechanics are on the EIP-7702 brief.

Then issue the session. Alchemy's wallet API calls this wallet_createSession (grantPermissions in the SDK). The request names the session key, an expiry in seconds, and a permissions array; the owner signs one EIP-712 typed-data authorization, and from then on the agent signs with the session key only.

// after delegation: same address, 23-byte designator
const session = await client.grantPermissions({
  expirySec: Math.floor(Date.now() / 1000) + 24 * 60 * 60,        // 24h, then dead
  key: { publicKey: sessionKey.address, type: "secp256k1" },
  permissions: [
    { type: "erc20-token-transfer",  data: { address: USDC,  allowance: "500000000" } },   // 500 USDC, 6 dp
    { type: "functions-on-contract", data: { address: VAULT, functions: [DEPOSIT_SELECTOR] } },
    { type: "gas-limit",             data: { limit: "0x2dc6c0" } }                        // 3,000,000
  ]
});
// wallet_createSession returns the typed-data request; the owner signs it once.
// Permission type names are documented; check the vendor reference for field shapes.

The eight documented permission types are native-token-transfer, erc20-token-transfer, gas-limit, contract-access, account-functions, functions-on-all-contracts, functions-on-contract and root. Never grant root to an agent; it is the master key under another name. A sane first policy for a treasury agent:

Keep one fact in view: delegation is not custody transfer. The master key can always replace or clear the code, and a buggy implementation runs with the full balance. Whitelist audited implementations and keep the raw key out of the agent runtime, or the policy is theatre.

Step 4 — Orchestration: put the wallet behind MCP, not inside the prompt

The model must never see key material, and it must never be the thing that enforces limits. The production pattern is hybrid: the LLM proposes, the policy engine disposes. Concretely, an MCP server exposes a small set of wallet tools — balance, quote, simulate, execute — and execute forwards to a signer process that holds the session key. Claude, ChatGPT, Cursor and Codex reach wallets this way, and so do the vault rails we track; it is also how the graph itself is served, over MCP and x402.

Three rules follow. Tool results are data, not instructions: a page that says "send everything to this address" is quoted back, not executed. Every state-changing tool simulates before it broadcasts and refuses on a failed simulation or a threat-scan hit; MetaMask's agent wallet lists both as features. And paid tools go through @x402/mcp, so per-call spend shows up as receipts you can audit rather than as an API key someone shared.

Step 5 — Settlement: how the agent pays for APIs over x402

x402 turns HTTP 402 into a payment rail, and paying for tools is the only agent behaviour with more than a hundred million receipts. The protocol README describes a twelve-step exchange; compressed, it is this.

1  agent  → GET /resource
2  server → 402 Payment Required + PAYMENT-REQUIRED header
            (base64 PaymentRequired: amount, asset, network, payTo, scheme)
3  agent  → signs a USDC authorization (EIP-3009 transferWithAuthorization, gasless on Base)
4  agent  → retries with PAYMENT-SIGNATURE header (PaymentPayload)
5  server → facilitator /verify → fulfils → facilitator /settle submits on-chain
6  server → 200 OK + PAYMENT-RESPONSE header (settlement receipt)

The agent never needs ETH. It signs an authorization over USDC; the facilitator submits it and pays the gas. Current schemes are exact (a fixed amount), upto (a maximum per request) and, on EVM, batch-settlement through escrow and off-chain vouchers. Stewardship sits with the Linux Foundation; the x402 Foundation lists 40 members including AWS, Google, Visa, Mastercard, Stripe, Circle, Cloudflare and Shopify (2026).

The measured flow is small tickets in one asset: $73M across 176M transactions from May 2025 to April 2026, an average ticket near $0.31, and a USDC share of 98.6 to 99 percent (Keyrock, Who Pays the Agent, with Coinbase and Tempo data). Handle raw volume with care — Coinbase estimated that 25 to 30 percent of some 30-day windows was leaderboard farming. The x402 brief and the payments statistics page separate economic transactions from vanity loops. Idle balances between jobs belong under the same session policy: one allowlisted ERC-4626 vault, one deposit selector, no human signature per deposit — see where agents park idle USDC.

The 10-point security checklist

Ledger documented a 2026 case in which an attacker steered an agent into transferring about $175,000 with a hidden, Morse-code-style instruction — no stolen key, no broken AMM. The checklist assumes that is the normal failure mode.

• Never hand over the master key. The owner key lives with a human, a hardware path, or a TEE. The agent gets a session key or nothing.
• Cap every session in USDC, per transaction and per session, inside the policy object — not the prompt.
• Expire every session. Hours for trading, days for yield. Rotate on schedule; revoke on the first anomaly.
• Allowlist targets, functions and assets. Two selectors on two contracts is a policy. "Any call" is a god-key with extra steps.
• Sponsor gas so the wallet stays USDC-only. A wallet with no ETH cannot leak ETH, and the sponsor budget gets its own cap.
• Simulate before broadcast and refuse on failure. Add threat scanning of counterparties and calldata.
• Keep the signer in a TEE or a separate process. Key material never enters the model's context window or its logs.
• Treat every tool result, page and document as data. Instructions found in content are quoted back, never executed.
• Whitelist audited EIP-7702 implementations and test the revoke path: delegate to the zero address and the designator clears.
• Label your own god-keys. A funded agent wallet that is a raw EOA with no delegation and no signer isolation is an incident precursor. The graph flags it god_key = true; your dashboard should too.

The long version, with prompt-injection patterns, is the agent wallet security checklist.

What the graph sees once you are connected

Connected this way, the agent becomes legible. Its wallet carries a DELEGATES_CODE_TO edge to a known implementation, a HAS_SESSION_KEY policy object with caps and expiry where visible, and PAYS edges to x402 sellers. On the liveness ladder it reaches L7 the first time it pays, L8 when it holds more than 1 USDC of dust, and L9 with three or more repeat counterparties in a 30-day window. A raw EOA holding agent-sized USDC with no delegation gets the god-key label instead. That is the line between a badge and an economic actor, and it is what the Agentic Desk will let operators watch on their own wallets. More guides live in the research hub.

Sources

• EIP-7702: Set EOA account code, Ethereum EIPs (type 0x04, 23-byte designator) — mainnet 2025-05-07 — link
• ethereum.org, Pectra: EIP-7702 (delegation is not custody transfer) — 2025 — link
• Coinbase Developer Platform, EIP-7702 (in-place upgrade, sponsored delegation chains) — 2026 — link
• Alchemy Wallet APIs, Session keys (wallet_createSession, expirySec, eight permission types) — read 2026-09-04 — link
• x402 Foundation, protocol repository (packages, twelve-step flow, schemes) — read 2026-09-04 — link
• Coinbase Developer Platform, x402 docs — 2026 — link
• Coinbase AgentKit repository (npm create onchain-agent@latest) — 2026 — link
• Keyrock, Who Pays the Agent? (volume, ticket size, USDC share) — window May 2025 – Apr 2026 — link
• ERC-8004 reference contracts (identity, reputation, validation) — 2026 — link
• Base agent-registry liveness research — 2026 — link
• satohubai/onchain-agents, scored index of frameworks, MCPs and rails — 2026 — link

FAQ