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:

Feature	Reference	When to Read
Sign in with Base	references/authentication.md	Wallet auth, SIWE, backend verification, SignInWithBaseButton, Wagmi/Privy setup
Base Pay	references/payments.md	One-tap USDC payments, payerInfo, server-side verification, BasePayButton
Subscriptions	references/subscriptions.md	Recurring charges, spend permissions, CDP wallet setup, charge/revoke lifecycle
Sub Accounts	references/sub-accounts.md	App-specific embedded wallets, key generation, funding
Capabilities	references/capabilities.md	Batch transactions, gas sponsorship (paymasters), atomic execution, auxiliaryFunds, attribution
Prolinks	references/prolinks.md	Shareable payment links, QR codes, encoded transaction URLs
Troubleshooting	references/troubleshooting.md	Popup issues, gas usage, unsupported calls, migration, doc links

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