Building with Base Account

Base Account is an ERC-4337 smart wallet providing universal sign-on, one-tap USDC payments, and multi-chain support (Base, Arbitrum, Optimism, Zora, Polygon, BNB, Avalanche, Lordchain, Ethereum Mainnet).

Quick Start

npm install @base-org/account @base-org/account-ui

import { createBaseAccountSDK } from '@base-org/account';

const sdk = createBaseAccountSDK({
  appName: 'My App',
  appLogoUrl: 'https://example.com/logo.png',
  appChainIds: [8453], // Base Mainnet
});

const provider = sdk.getProvider();

Feature References

Read the reference for the feature you're implementing:

Critical Requirements

Security

• Track transaction IDs to prevent replay attacks
• Verify sender matches authenticated user to prevent impersonation
• Use a proxy to protect Paymaster URLs from frontend exposure
• Paymaster providers must be ERC-7677-compliant
• Never expose CDP credentials client-side (subscription backend only)

Popup Handling

• Generate nonces before user clicks "Sign in" to avoid popup blockers
• Use Cross-Origin-Opener-Policy: same-origin-allow-popups
• same-origin breaks the Base Account popup

Base Pay

• Base Pay works independently from SIWB — no auth required for pay()
• testnet param in getPaymentStatus() must match pay() call
• Never disable actions based on onchain balance alone — check auxiliaryFunds capability

Sub Accounts

• Call wallet_addSubAccount each session before use
• Ownership changes expected on new devices/browsers
• Only Coinbase Smart Wallet contracts supported for import

Smart Wallets

• ERC-6492 wrapper enables signature verification before wallet deployment
• Viem's verifyMessage/verifyTypedData handle this automatically

For Edge Cases and Latest API Changes

• AI-optimized docs: docs.base.org/llms.txt
• Full reference: docs.base.org/base-account