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.Omit<SubAccountOptions, 'enableAutoSubAccounts'>
Sub-account configuration options.
Show SubAccountOptions properties
Show SubAccountOptions properties
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
boolean
When
true (default), enables Auto Spend Permissions for sub-accounts. This allows automatic transfers from the user’s Base Account to the sub-account when funds are missing and attempts background transactions using existing spend permissions. Set to false to disable this behavior. Learn more in Auto Spend Permissions.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: {
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: {
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 };
}
}
});
// Create a sub-account
const subAccount = await sdk.subAccount.create({
type: 'create',
keys: [{
type: 'p256',
publicKey: '0x...'
}]
});
// Get existing sub-account
const existingSubAccount = 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
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.