Skip to content

Quick start

This guide will help you get started with Account Kit by setting up your environment, creating a smart account, and sending a User Operation (UO). By the end of this guide, you will have a basic understanding of how to use the SDK and where to look for more advanced use cases.

1. Install the packages

Run the following command in your project directory to install the required packages:

bash
npm init es6 -y
npm install -save-dev typescript
npm install @alchemy/aa-alchemy @alchemy/aa-core @alchemy/aa-accounts @alchemy/aa-signers viem
bash
yarn init -y
yarn add -D typescript
yarn add @alchemy/aa-alchemy @alchemy/aa-core @alchemy/aa-accounts @alchemy/aa-signers viem

Note

Next, install viem by running the below command. Viem contains helpful abstractions and modules that are useful when using Account Kit. Additionally, many Account Kit modules use viem themselves.

Make sure your new package.json file looks similar to the one below. Note that we have "type": module in package.json for this example:

json
{
  "name": "account-kit-test",
  "version": "1.0.0",
  "description": "An Example Using Account Kit",
  "main": "index.ts",
  "type": "module",
  "license": "ISC",
  "devDependencies": {
    "typescript": "^5.2.2"
  },
  "dependencies": {
    "@alchemy/aa-accounts": "^*", // latest version
    "@alchemy/aa-alchemy": "^*", // latest version
    "@alchemy/aa-core": "^*", // latest version
    "viem": "^*" // latest version compatible with aa-sdk
  }
}

Also make sure your Node version is 18.16.0 using your version manager:

bash
nvm install 18.16.0
nvm use 18.16.0
bash
asdf install nodejs 18.16.0
asdf global nodejs 18.16.0
asdf reshim nodejs

Lastly, create a file called index.ts in the project to write the code you will see below!

2. Get your Alchemy API Key

To read or write any data to a blockchain, you will need an Alchemy API Key and RPC URL. Go to the Alchemy Dashboard and access your credentials from the dashboard.

Account Kit Overview

3. Query your Smart Account Address

TIP

Don't use hardcoded private keys in production, like the example below. Instead, follow the Alchemy Signer guide to build a secure user friendly Embedded Account!

Using the SDK in the following example, we will use Account Kit to generate the address of your smart account from which to send a UO eventually.

ts
import { createModularAccountAlchemyClient } from "@alchemy/aa-alchemy";
import { LocalAccountSigner, sepolia, type Hex } from "@alchemy/aa-core";

const chain = sepolia;

// The private key of your EOA that will be the signer to connect with the Modular Account
// Our recommendation is to store the private key in an environment variable
const PRIVATE_KEY = "0xYourEOAPrivateKey" as Hex;
const signer = LocalAccountSigner.privateKeyToAccountSigner(PRIVATE_KEY);

// Create a smart account client to send user operations from your smart account
const client = await createModularAccountAlchemyClient({
  // get your Alchemy API key at https://dashboard.alchemy.com
  apiKey: "ALCHEMY_API_KEY",
  chain,
  signer,
});

(async () => {
  // Fund your account address with ETH to send for the user operations
  // (e.g. Get Sepolia ETH at https://sepoliafaucet.com)
  console.log("Smart Account Address: ", client.getAddress()); // Log the smart account address
})();

Copy the above into index.ts. To run the script, do the following:

bash
npx tsx index.ts

You will get a response like this in your terminal:

Smart Account Address: 0xYOUR_SMART_ACCOUNT_ADDRESS

4. Fund your Smart Account

At scale, you can use our Gas Manager to sponsor User Operations for smart accounts so the user doesn't need to fund their account.

But for this quickstart guide, and because we are developing on a testnet, let's fund the account using the Alchemy Faucet. Simply log in with Alchemy and claim your testnet tokens for free.

Account Kit Overview

5. Send a User Operation using Account Kit

Finally, deploy the newly funded smart account and send a UO on its behalf.

ts
import { createModularAccountAlchemyClient } from "@alchemy/aa-alchemy";
import {
  Address,
  LocalAccountSigner,
  sepolia,
  type Hex,
} from "@alchemy/aa-core";

// select your chain from @alchemy/aa-core
const chain = sepolia;

// The private key of your EOA that will be the signer to connect with the Modular Account
const PRIVATE_KEY = "0xYourEOAPrivateKey" as Hex;
const signer = LocalAccountSigner.privateKeyToAccountSigner(PRIVATE_KEY);


(async () => {
  // Create a smart account client to send user operations from your smart account
  const client = await createModularAccountAlchemyClient({
    // get your Alchemy API key at https://dashboard.alchemy.com
    apiKey: "ALCHEMY_API_KEY",
    chain,
    signer,
  });

  // Fund your account address with ETH to send for the user operations
  // (e.g. Get Sepolia ETH at https://sepoliafaucet.com)
  console.log("Smart Account Address: ", client.getAddress()); // Log the smart account address

  const vitalikAddress =
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" as Address;
  // Send a user operation from your smart account to Vitalik that does nothing
  const { hash: uoHash } = await client.sendUserOperation({
    uo: {
      target: vitalikAddress, // The desired target contract address
      data: "0x", // The desired call data
      value: 0n, // (Optional) value to send the target contract address
    },
  });

  console.log("UserOperation Hash: ", uoHash); // Log the user operation hash

  // Wait for the user operation to be mined
  const txHash = await client.waitForUserOperationTransaction({
    hash: uoHash,
  });

  console.log("Transaction Hash: ", txHash); // Log the transaction hash
})();

Copy the above to replace what's in index.ts. To run the full example script above, do:

bash
npx tsx index.ts

And that's it! You should see the following on your terminal:

Smart Account Address: 0xYOUR_SMART_ACCOUNT_ADDRESS
UserOperation Hash: 0xYOUR_UO_HASH
Transaction Hash: 0xYOUR_TXN_HASH

Note

The UO hash is what our Bundler returns once it submits the UO to the Blockchain on behalf of your smart account. You will want to use the Transaction Hash to know when the UO is mined on a blockchain to query information about it.

Handling Errors

When running the above script, you might see the following errors:

  1. "precheck failed: maxFeePerGas is XXX but must be at least XXX, which is based on the current block base fee."
  2. "precheck failed: sender balance and deposit together is XXX but must be at least XXX to pay for this operation."
  3. "Failed to find transaction for User Operation."

These are due to increased network activity at that time and are fleeting issues. Running the script again will resolve them naturally.

Since this "Getting started" example is a simple script, you must consider how Account Kit can work in various applications.

6. Use Alchemy Signer

In this example, we used a Local Signer. As the next step to a production ready app, follow this Alchemy Signer guide to build an Embedded Account with email, passkey (i.e. biometrics), and soon social auth flows!

Dive deeper

In this guide, we initialized an AlchemySmartAccountClient with the aa-alchemy package to send a UO. However, you can do much more with Account Kit and its many packages.

  1. To learn more about the different packages and their use cases, check out the Packages overview section.

  2. To learn more about different smart account options available for your applications, check out the section Choosing a smart account.

  3. To learn more about different signer options for your smart accounts, check out the section on Choosing a signer.

  4. To learn more about how to use your smart accounts and what Account Kit offers to enhance users' web3 experience, check out a number of guides we have in the Using smart accounts section, covering from basic to advanced usages.