> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation and setup

> Install the Startale AA SDK and pick a signer that fits your stack.

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.

<Note>
  The SDK source is at [`StartaleGroup/scs-aa-sdk`](https://github.com/StartaleGroup/scs-aa-sdk) and the published package is `@startale-scs/aa-sdk`.
</Note>

## Install the SDK

The minimum runtime dependencies are the SDK itself plus `viem`:

```bash theme={null}
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](/aa-sdk/auth-providers/dynamic). | Provides the wallet that exposes the signer.          |
| `@privy-io/react-auth`            | You authenticate with [Privy](/aa-sdk/auth-providers/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:

```bash .env theme={null}
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_..."
```

<Warning>
  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.
</Warning>

## Pick a signer

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

```ts theme={null}
import { toStartaleSmartAccount } from "@startale-scs/aa-sdk"

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

<Tabs>
  <Tab title="Viem LocalAccount (server / scripts)">
    A `LocalAccount` holds a private key directly. Best for backend services, scheduled jobs, or developer scripts.

    ```ts theme={null}
    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. |
  </Tab>

  <Tab title="Viem WalletClient (browser, raw viem)">
    A `WalletClient` is the viem object wrapping a connected browser wallet. Best for browser apps that use viem directly.

    ```ts theme={null}
    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`). |
  </Tab>

  <Tab title="EIP-1193 provider (Privy, Dynamic, MetaMask)">
    Pass the raw provider straight to `toStartaleSmartAccount`. The SDK calls `eth_accounts` internally to resolve the signing address.

    ```ts theme={null}
    const provider = await wallets[0].getEthereumProvider() // example: Privy

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

    See the [Privy](/aa-sdk/auth-providers/privy) and [Dynamic](/aa-sdk/auth-providers/dynamic) integration pages for the full flow.
  </Tab>

  <Tab title="Ethers Wallet (legacy code)">
    Codebases that already pass `ethers` wallets around can keep doing so.

    ```ts theme={null}
    import { Wallet } from "ethers"

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

    The SDK detects ethers wallets and adapts them internally.
  </Tab>
</Tabs>

## 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.

```ts theme={null}
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:

```ts theme={null}
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](/aa-sdk/tutorials/smart-account-setup).

## Next steps

<CardGroup cols={2}>
  <Card title="Smart account setup" icon="wallet" href="/aa-sdk/tutorials/smart-account-setup">
    Wrap the account in a React provider and initialise sponsored and ERC-20 clients.
  </Card>

  <Card title="Contract interactions" icon="layer-group" href="/aa-sdk/tutorials/contract-interactions">
    Send single and batched calls through the smart account.
  </Card>

  <Card title="Auth providers" icon="user-check" href="/aa-sdk/auth-providers/overview">
    Plug Dynamic or Privy into the signer slot for social login.
  </Card>

  <Card title="Portal setup" icon="key" href="/aa-sdk/tutorials/portal">
    If you have not provisioned a paymaster yet, do that first.
  </Card>
</CardGroup>