Skip to content

Quickstart

This guide creates a smart account directly from a local private key using @0xgasless/smart-account + viem. Use this path when you have your own signer — a viem account, an ethers wallet, a hardware device, or a key you manage yourself — and just want the ERC-4337 layer on top.

Create a new directory and initialize the project:

Terminal window
mkdir my-smart-account-app
cd my-smart-account-app
npm init -y

Install the dependencies:

Terminal window
npm install viem @0xgasless/smart-account
npm install --save-dev typescript @types/node ts-node

Create a tsconfig.json:

Terminal window
npx tsc --init

Update your package.json to allow ES modules:

{
"name": "my-smart-account-app",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "ts-node src/index.ts"
}
}

Create a src directory and an index.ts file inside it. Add the following code to initialize the smart account signer using a local private key.

Note: Never commit private keys to GitHub. We use a hardcoded one here for demonstration purposes, but you should use environment variables (process.env.PRIVATE_KEY) in production.

import {
createSmartAccountClient,
createECDSAOwnershipValidationModule,
} from "@0xgasless/smart-account";
import { privateKeyToAccount } from "viem/accounts";
import { avalancheFuji } from "viem/chains";
import { createWalletClient, http, parseAbi, encodeFunctionData } from "viem";
const API_KEY = "YOUR_API_KEY"; // Replace with your actual key
const RPC_URL = "https://api.avax-test.network/ext/bc/C/rpc";
const BUNDLER_URL = "https://bundler.0xgasless.com/43113"; // Avalanche Fuji
const PAYMASTER_URL = `https://paymaster.0xgasless.com/v1/43113/rpc/${API_KEY}`;
// Your signer (use an env var in real code)
const signer = createWalletClient({
account: privateKeyToAccount("0x..."),
chain: avalancheFuji,
transport: http(RPC_URL),
});
async function main() {
console.log("Setting up smart account...");
// The SDK's default contracts are for mainnet; on Fuji pass the Fuji ones.
const ecdsaModule = await createECDSAOwnershipValidationModule({
signer,
moduleAddress: "0xcfb0BA514aa398085D63eC70cfEa6EC7f1094E8F",
});
// Create the smart account client
const smartAccount = await createSmartAccountClient({
signer,
chainId: 43113,
rpcUrl: RPC_URL,
bundlerUrl: BUNDLER_URL,
paymasterUrl: PAYMASTER_URL,
factoryAddress: "0xF0b3f5146c2725e36d78F5029bc560eDfc67ADe0",
implementationAddress: "0x8aF33bE7af021A6075aeB19b076fC75Bfbd2c5c3",
defaultFallbackHandler: "0xdA62055b0730d1d0621aD0A446DcD6057a6d951E",
defaultValidationModule: ecdsaModule,
activeValidationModule: ecdsaModule,
});
const address = await smartAccount.getAccountAddress();
console.log("Smart Account deployed (or counterfactual) address:", address);

Let’s mint a free NFT on Avalanche Fuji to test our gasless setup.

console.log("Preparing transaction...");
const nftContractAddress = "0xYourTestNFTAddress"; // Replace with a verifiable testnet contract
const abi = parseAbi(["function safeMint(address to)"]);
// Encode the contract call
const callData = encodeFunctionData({
abi,
functionName: "safeMint",
args: [address], // Minting the NFT to the smart account itself
});
console.log("Sending UserOperation to the Bundler...");
const userOpResponse = await smartAccount.sendTransaction({
to: nftContractAddress,
data: callData,
value: 0n,
});
const hash = await userOpResponse.waitForTxHash();
console.log("UserOperation Hash:", hash);
const receipt = await userOpResponse.wait();
console.log("Transaction mined! Receipt:", receipt.receipt.transactionHash);
}
main().catch(console.error);

Execute the script:

Terminal window
npm start

If successful, you will see the smart account address and the transaction hash logged to your console. Since we provided a paymasterUrl, the user pays zero gas, 0xGasless sponsors it through your Paymaster policy.