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:
npm init es6 -y
npm install -save-dev typescript
npm install @alchemy/aa-alchemy @alchemy/aa-core @alchemy/aa-accounts @alchemy/aa-signers viem
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:
{
"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:
nvm install 18.16.0
nvm use 18.16.0
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.
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.
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:
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.
5. Send a User Operation using Account Kit
Finally, deploy the newly funded smart account and send a UO on its behalf.
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:
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:
- "precheck failed: maxFeePerGas is XXX but must be at least XXX, which is based on the current block base fee."
- "precheck failed: sender balance and deposit together is XXX but must be at least XXX to pay for this operation."
- "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.
To learn more about the different packages and their use cases, check out the Packages overview section.
To learn more about different smart account options available for your applications, check out the section Choosing a smart account.
To learn more about different
signer
options for your smart accounts, check out the section on Choosing a signer.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.