Creates a Base Account SDK instance that provides an EIP-1193 compliant Ethereum provider and additional account management functionality. This is the primary entry point for integrating Base Account into your application.
Parameters
CreateProviderOptions
required
Configuration options for creating the SDK instance.
Show CreateProviderOptions properties
Show CreateProviderOptions properties
string
The name of your application. Defaults to “App” if not provided.
string
URL to your application’s logo image. Used in wallet UI. Defaults to empty string if not provided.
number[]
Array of chain IDs that your application supports. Defaults to empty array if not provided.
Preference
Optional preferences for SDK behavior.
Show Preference properties
Show Preference properties
string
Custom wallet URL override. Only use when overriding the default wallet URL with a custom environment.
Attribution
boolean
Whether to enable functional telemetry. Defaults to
true.SubAccountOptions
Sub-account configuration options.
Show SubAccountOptions properties
Show SubAccountOptions properties
'on-connect' | 'manual'
Controls when sub-accounts are created. Defaults to
'manual'.'on-connect': Automatically creates a sub-account when connecting to the wallet (automatically injectsaddSubAccountcapability towallet_connect)'manual': Requires explicitwallet_addSubAccountcall to create a sub-account
'sub' | 'universal'
Controls which account is used by default when no account is specified. Defaults to
'universal'.'sub': Sub-account is the default account (first in accounts array)'universal': Universal account is the default account (first in accounts array)
'spend-permissions' | 'manual'
Controls how sub-accounts are funded. Defaults to
'spend-permissions'.'spend-permissions': Routes through universal account if no spend permissions exist, handles insufficient balance errors automatically. Learn more in Auto Spend Permissions'manual': Direct execution from sub-account without automatic fallbacks
ToOwnerAccountFn
Function that returns the owner account for signing sub-account transactions.
Where
Show ToOwnerAccountFn signature
Show ToOwnerAccountFn signature
type ToOwnerAccountFn = () => Promise<{ account: OwnerAccount | null; }>
OwnerAccount is a union type of:LocalAccount(from viem) - A local account with private keyWebAuthnAccount(from viem) - A WebAuthn-based account for passkey authentication
Record<number, string>
Mapping of chain IDs to paymaster URLs for gasless transactions.
Returns
BaseAccountSDK
SDK instance with provider and sub-account management capabilities.
Show BaseAccountSDK properties
Show BaseAccountSDK properties
() => ProviderInterface
Returns an EIP-1193 compliant Ethereum provider that can be used with web3 libraries like Viem, Wagmi, and Web3.js.
SubAccountManager
Sub-account management methods.
Show SubAccountManager properties
Show SubAccountManager properties
(account: AddSubAccountAccount) => Promise<SubAccount>
Creates a new sub-account.
() => Promise<SubAccount | null>
Retrieves the current sub-account information.
(params: AddOwnerParams) => Promise<string>
Adds an owner to the sub-account.
(fn: ToOwnerAccountFn) => void
Sets the function for determining the owner account. The function should return a Promise resolving to an object with an
account property that is either a LocalAccount, WebAuthnAccount, or null.import { createBaseAccountSDK } from '@base-org/account';
import { base } from 'viem/chains';
const sdk = createBaseAccountSDK({
appName: 'My DApp',
appLogoUrl: 'https://mydapp.com/logo.png',
appChainIds: [base.id],
});
const provider = sdk.getProvider();
import { createBaseAccountSDK } from '@base-org/account';
import { base, baseSepolia } from 'viem/chains';
const sdk = createBaseAccountSDK({
appName: 'My Advanced DApp',
appLogoUrl: 'https://mydapp.com/logo.png',
appChainIds: [base.id, baseSepolia.id],
preference: {
attribution: {
auto: true
},
telemetry: true
},
subAccounts: {
creation: 'on-connect', // Auto-create sub-account on connection
defaultAccount: 'sub', // Use sub-account by default
funding: 'spend-permissions', // Auto-handle funding
toOwnerAccount: async () => ({
account: cryptoAccount?.account || null
})
},
paymasterUrls: {
[base.id]: 'https://paymaster.base.org',
[baseSepolia.id]: 'https://paymaster.base-sepolia.org'
}
});
import { createBaseAccountSDK } from '@base-org/account';
const sdk = createBaseAccountSDK({
appName: 'Sub-Account App',
appChainIds: [8453],
subAccounts: {
creation: 'manual', // Explicitly create sub-accounts when needed
defaultAccount: 'universal', // Universal account is default
funding: 'spend-permissions', // Auto-handle insufficient balance
toOwnerAccount: async () => {
// Return the owner account that will sign sub-account transactions
// mainAccount should be a LocalAccount or WebAuthnAccount from viem
return { account: mainAccount || null };
}
}
});
// Manually create a sub-account when needed
const subAccount = await sdk.subAccount.create({
type: 'create',
keys: [{
type: 'p256',
publicKey: '0x...'
}]
});
import { createBaseAccountSDK } from '@base-org/account';
const sdk = createBaseAccountSDK({
appName: 'Auto Sub-Account App',
appChainIds: [8453],
subAccounts: {
creation: 'on-connect', // Auto-create on wallet connection
defaultAccount: 'sub', // Sub-account is default
funding: 'spend-permissions', // Auto-handle insufficient balance
toOwnerAccount: async () => {
return { account: mainAccount || null };
}
}
});
// Sub-account is automatically created on connection
const provider = sdk.getProvider();
await provider.request({ method: 'eth_requestAccounts' });
// Sub-account is automatically available
const subAccount = await sdk.subAccount.get();
Integration Examples
With Viem
import { createWalletClient, custom } from 'viem';
import { base } from 'viem/chains';
import { createBaseAccountSDK } from '@base-org/account';
const sdk = createBaseAccountSDK({
appName: 'Viem Integration',
appChainIds: [base.id]
});
const provider = sdk.getProvider();
const client = createWalletClient({
chain: base,
transport: custom(provider)
});
With Wagmi
import { createConfig, custom } from 'wagmi';
import { base } from 'wagmi/chains';
import { createBaseAccountSDK } from '@base-org/account';
const sdk = createBaseAccountSDK({
appName: 'Wagmi Integration',
appChainIds: [base.id]
});
const provider = sdk.getProvider();
const config = createConfig({
chains: [base],
transports: {
[base.id]: custom(provider),
},
});
Configuration Options
Sub-Account Configuration
Configure sub-account behavior with three independent options:const sdk = createBaseAccountSDK({
appName: 'My App',
appChainIds: [8453],
subAccounts: {
creation: 'on-connect' | 'manual', // When to create
defaultAccount: 'sub' | 'universal', // Which is default
funding: 'spend-permissions' | 'manual', // How to fund transactions
toOwnerAccount: async () => ({ account }) // Owner for signing
}
});
// Most seamless UX: Auto-create, use sub-account by default, auto-fund
subAccounts: {
creation: 'on-connect',
defaultAccount: 'sub',
funding: 'spend-permissions'
}
// Manual control: Create when needed, universal default, auto-fund
subAccounts: {
creation: 'manual',
defaultAccount: 'universal',
funding: 'spend-permissions'
}
// Full manual: Complete developer control
subAccounts: {
creation: 'manual',
defaultAccount: 'universal',
funding: 'manual'
}
Attribution
Configure transaction attribution for analytics and tracking:// Auto-generate attribution from app origin
const sdk = createBaseAccountSDK({
appName: 'My App',
preference: {
attribution: { auto: true }
}
});
// Custom attribution data
const sdk = createBaseAccountSDK({
appName: 'My App',
preference: {
attribution: { dataSuffix: '0x1234567890123456789012345678901234567890' }
}
});
Paymaster Integration
Enable gasless transactions with paymaster URLs:const sdk = createBaseAccountSDK({
appName: 'Gasless App',
appChainIds: [8453, 84532],
paymasterUrls: {
8453: 'https://paymaster.base.org/api/v1/sponsor',
84532: 'https://paymaster.base-sepolia.org/api/v1/sponsor'
}
});
Error Handling
The SDK initialization is synchronous and will validate preferences during creation:try {
const sdk = createBaseAccountSDK({
appName: 'My App',
appChainIds: [8453],
subAccounts: {
toOwnerAccount: invalidFunction // Will throw validation error
}
});
} catch (error) {
console.error('SDK initialization failed:', error);
}
TypeScript Support
The SDK is fully typed for TypeScript development:import type {
CreateProviderOptions,
BaseAccountSDK,
ProviderInterface,
ToOwnerAccountFn
} from '@base-org/account';
import { LocalAccount } from 'viem';
const toOwnerAccount: ToOwnerAccountFn = async () => {
// Your logic to get the owner account
const ownerAccount: LocalAccount | null = getOwnerAccount();
return { account: ownerAccount };
};
const options: CreateProviderOptions = {
appName: 'Typed App',
appChainIds: [8453],
subAccounts: {
toOwnerAccount
}
};
const sdk: BaseAccountSDK = createBaseAccountSDK(options);
const provider: ProviderInterface = sdk.getProvider();
The SDK automatically manages Cross-Origin-Opener-Policy validation and telemetry initialization. Make sure your application’s headers allow popup windows if using the default wallet interface.
The
createBaseAccountSDK function is the primary entry point for Base Account integration. It provides both a standard EIP-1193 provider and advanced features like sub-account management and gasless transactions.