building-with-base-account

Integrates Base Account SDK for authentication and payments. Covers Sign in with Base (SIWB), Base Pay, Paymasters, Sub Accounts, Spend Permissions, Prolinks, and batch transactions. Use when building apps with wallet authentication, USDC payments, sponsored transactions, smart wallet features, recurring subscriptions, shareable payment links, or any onchain interaction on Base. Covers phrases like "add sign in with Base", "SIWB button", "accept USDC payments", "Base Pay", "paymaster setup", "gas sponsorship", "smart wallet", "sub account", "spend permissions", or "payment link".

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