Installation and setup

This page covers the framework-agnostic setup: installing the SDK, configuring environment variables, and choosing a signer. The SDK does not assume Next.js, React, wagmi, or any particular auth provider; pick whichever signer fits your project.

The SDK source is at StartaleGroup/scs-aa-sdk and the published package is @startale-scs/aa-sdk.

Install the SDK

The minimum runtime dependencies are the SDK itself plus viem:

npm install @startale-scs/aa-sdk viem

Add the optional packages below only if your app uses them. None of them are required by @startale-scs/aa-sdk:

Package	Add it when	Why
`@rhinestone/module-sdk`	You install or build custom ERC-7579 modules.	Provides typed helpers for module init data.
`wagmi` + `@tanstack/react-query`	You already use wagmi for connection state.	Lets you reuse wagmi’s `WalletClient` as the signer.
`@dynamic-labs/sdk-react-core`	You authenticate with Dynamic.	Provides the wallet that exposes the signer.
`@privy-io/react-auth`	You authenticate with Privy.	Provides the embedded wallet that exposes the signer.
`ethers`	You already pass `ethers` wallets around your codebase.	The SDK accepts `EthersWallet` directly as a signer.

Configure runtime credentials

The SDK takes the bundler URL, paymaster URL, and paymasterId at call time. Where you store them is up to your framework. A plain .env file works for any Node-based runtime:

.env

BUNDLER_URL="https://soneium-minato.bundler.scs.startale.com?apikey=YOUR_API_KEY"
PAYMASTER_URL="https://paymaster.scs.startale.com/v1?apikey=YOUR_API_KEY"
PAYMASTER_ID="pm_..."

Keep your API key on the server when possible. If you must expose it to the browser (for example, in a single-page app without a backend), prefer per-domain SCS API keys with a tight gas policy so a leak has bounded blast radius. The SDK does not require any specific environment variable prefix; framework-specific prefixes like NEXT_PUBLIC_* or VITE_* are not part of the SDK’s contract.

Pick a signer

toStartaleSmartAccount accepts any of the signer types below. The choice is yours and depends on how your app already manages keys.

import { toStartaleSmartAccount } from "@startale-scs/aa-sdk"

const account = await toStartaleSmartAccount({
  signer,                 // pick one of the four shapes below
  chain,
  transport: http(),
  index: 0n,
})

Viem LocalAccount (server / scripts)
Viem WalletClient (browser, raw viem)
EIP-1193 provider (Privy, Dynamic, MetaMask)
Ethers Wallet (legacy code)

A LocalAccount holds a private key directly. Best for backend services, scheduled jobs, or developer scripts.

import { privateKeyToAccount } from "viem/accounts"

const signer = privateKeyToAccount(process.env.OWNER_PRIVATE_KEY as `0x${string}`)

Symbol	Source	Role
`privateKeyToAccount`	`viem/accounts`	Builds a `LocalAccount` from a hex private key.

A WalletClient is the viem object wrapping a connected browser wallet. Best for browser apps that use viem directly.

import { createWalletClient, custom } from "viem"
import { soneiumMinato } from "viem/chains"

const signer = createWalletClient({
  account: connectedAddress as `0x${string}`,
  chain: soneiumMinato,
  transport: custom(window.ethereum!),
})

Symbol	Source	Role
`createWalletClient` / `custom`	`viem`	Build a wallet client over an EIP-1193 provider.
`soneiumMinato`	`viem/chains`	Soneium Minato chain definition (chain id `1946`).

Pass the raw provider straight to toStartaleSmartAccount. The SDK calls eth_accounts internally to resolve the signing address.

const provider = await wallets[0].getEthereumProvider() // example: Privy

const account = await toStartaleSmartAccount({
  signer: provider,
  chain,
  transport: http(),
  index: 0n,
})

See the Privy and Dynamic integration pages for the full flow.

Codebases that already pass ethers wallets around can keep doing so.

import { Wallet } from "ethers"

const signer = new Wallet(process.env.OWNER_PRIVATE_KEY!)

The SDK detects ethers wallets and adapts them internally.

Optional: wagmi alongside the SDK

If your app already uses wagmi for connection state, you can keep wagmi for connection management and feed its WalletClient into toStartaleSmartAccount as a signer. wagmi is not required by the SDK.

import { useWalletClient } from "wagmi"
import { toStartaleSmartAccount } from "@startale-scs/aa-sdk"
import { http } from "viem"
import { soneiumMinato } from "viem/chains"

const { data: walletClient } = useWalletClient()

const account = await toStartaleSmartAccount({
  signer: walletClient!, // viem WalletClient from wagmi
  chain: soneiumMinato,
  transport: http(),
  index: 0n,
})

Symbol	Source	Role
`useWalletClient`	`wagmi`	Hook that returns a viem `WalletClient` for the currently connected wallet.
`toStartaleSmartAccount`	`@startale-scs/aa-sdk`	Builds the smart account from any supported signer.
`http`	`viem`	HTTP transport used by the smart account for RPC reads.

Sanity check

Before moving on, confirm you can read your smart account address on Soneium Minato:

import { http, createPublicClient } from "viem"
import { soneiumMinato } from "viem/chains"
import { toStartaleSmartAccount } from "@startale-scs/aa-sdk"

const publicClient = createPublicClient({ chain: soneiumMinato, transport: http() })

const account = await toStartaleSmartAccount({
  signer,
  chain: soneiumMinato,
  transport: http(),
  index: 0n,
})

console.log("counterfactual address:", account.address)
console.log("is delegated EIP-7702 account:", await account.isDelegated())

If the address prints, the SDK can talk to Soneium and you are ready for Smart account setup.

Next steps

Smart account setup

Wrap the account in a React provider and initialise sponsored and ERC-20 clients.

Contract interactions

Send single and batched calls through the smart account.

Auth providers

Plug Dynamic or Privy into the signer slot for social login.

Portal setup

If you have not provisioned a paymaster yet, do that first.

Overview

Getting started

Tutorials

Auth providers

Advanced

EIP-7702

Resources

FAQ

Install the SDK

Configure runtime credentials

Pick a signer

Optional: wagmi alongside the SDK

Sanity check

Next steps

Smart account setup

Contract interactions

Auth providers

Portal setup

​Install the SDK

​Configure runtime credentials

​Pick a signer

​Optional: wagmi alongside the SDK

​Sanity check

​Next steps

Smart account setup

Contract interactions

Auth providers

Portal setup

Install the SDK

Configure runtime credentials

Pick a signer

Optional: wagmi alongside the SDK

Sanity check

Next steps