createBaseAccountSDK

Create a Base Account SDK instance with EIP-1193 compliant provider

Defined in the Base Account SDK

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

params · CreateProviderOptions · required

Configuration options for creating the SDK instance.

Show CreateProviderOptions properties

appName · string

The name of your application. Defaults to “App” if not provided.

appLogoUrl · string

URL to your application’s logo image. Used in wallet UI. Defaults to empty string if not provided.

appChainIds · number[]

Array of chain IDs that your application supports. Defaults to empty array if not provided.

preference · Preference

Optional preferences for SDK behavior.

Show Preference properties

walletUrl · string

Custom wallet URL override. Only use when overriding the default wallet URL with a custom environment.

attribution · Attribution

Attribution configuration for Smart Wallet transactions.

Show Attribution properties

auto · boolean

When true, Smart Wallet will generate a 16 byte hex string from the app’s origin.

dataSuffix · `0x${string}`

Custom 16 byte hex string appended to initCode and executeBatch calldata. Cannot be used with auto: true.

telemetry · boolean

Whether to enable functional telemetry. Defaults to true.

subAccounts · Omit<SubAccountOptions, 'enableAutoSubAccounts'>

Sub-account configuration options.

Show SubAccountOptions properties

toOwnerAccount · ToOwnerAccountFn

Function that returns the owner account for signing sub-account transactions.

Show ToOwnerAccountFn signature

type ToOwnerAccountFn = () => Promise<{ account: OwnerAccount | null; }>

Where OwnerAccount is a union type of:

• LocalAccount (from viem) - A local account with private key
• WebAuthnAccount (from viem) - A WebAuthn-based account for passkey authentication

unstable_enableAutoSpendPermissions · 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.

paymasterUrls · Record<number, string>

Mapping of chain IDs to paymaster URLs for gasless transactions.

Returns

sdk · BaseAccountSDK

SDK instance with provider and sub-account management capabilities.

Show BaseAccountSDK properties

getProvider · () => ProviderInterface

Returns an EIP-1193 compliant Ethereum provider that can be used with web3 libraries like Viem, Wagmi, and Web3.js.

subAccount · SubAccountManager

Sub-account management methods.

Show SubAccountManager properties

create · (account: AddSubAccountAccount) => Promise<SubAccount>

Creates a new sub-account.

get · () => Promise<SubAccount | null>

Retrieves the current sub-account information.

addOwner · (params: AddOwnerParams) => Promise<string>

Adds an owner to the sub-account.

setToOwnerAccount · (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.

Basic Setup

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();

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.