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.
Prerequisites
Section titled “Prerequisites”- Node.js installed
- A package manager (
npm,yarn,pnpm, orbun) - An API key from the 0xGasless Dashboard
1. Setup Your Project
Section titled “1. Setup Your Project”Create a new directory and initialize the project:
mkdir my-smart-account-appcd my-smart-account-appnpm init -yInstall the dependencies:
npm install viem @0xgasless/smart-accountnpm install --save-dev typescript @types/node ts-nodeCreate a tsconfig.json:
npx tsc --initUpdate 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" }}2. Initialize the Account
Section titled “2. Initialize the Account”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 keyconst RPC_URL = "https://api.avax-test.network/ext/bc/C/rpc";const BUNDLER_URL = "https://bundler.0xgasless.com/43113"; // Avalanche Fujiconst 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);3. Execute a Transaction
Section titled “3. Execute a Transaction”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);4. Run it
Section titled “4. Run it”Execute the script:
npm startIf 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.
Next steps
Section titled “Next steps”- Bundlers — how UserOperations land on-chain.
- Paymasters — how the gas you just skipped got sponsored.
- Batch Transactions — atomic multi-call flows.