Command Line Examples

A collection of example scripts for working with ERC-4337 and account abstraction.

The ERC-4337 examples repository is a collection of scripts for building smart contract accounts. The repository comes with built in CLI commands to showcase features from well known contract implementations. The code can also be used as a reference on how to build account abstraction into your own applications.


To get started, clone the repository and install the dependancies.

git clone [email protected]:stackup-wallet/erc-4337-examples.git
cd erc-4337-examples
yarn install


The examples relies on a few commonly used config values. Make sure to set these up before running any of the commands.

yarn run init

This will create a config.json file in your local directory with the following values.

KeyDefault valueDescription
rpcUrl standard RPC URL for an EVM node that also supports all ERC-4337 bundler methods. You will need to fill in the API_KEY from the Stackup dashboard. Alternatively you can also use any RPC url that is enabled as a bundler.
signingKeyRandomly generated with ethers.jsThe key used to generate a UserOperation signature. The signature is used by the contract account to validate transactions.
paymaster.rpcUrl RPC URL to request paymaster approval when using the --withPaymaster flag. The examples assume that any paymaster service follows the interface specified here.
paymaster.contextempty objectThis arbitrary object is passed as the last parameter when calling pm_sponsorUserOperation. Its content will depend on the the specific paymaster you're interacting with.


Once your config is setup, the following pages will document commands you can use to run example scripts based on certain contract implementations.


Need to see the code?

The location of each script mimics the command structure. For example yarn run simpleAccount address will be located in scripts/simpleAccount/address.ts.

All commands can also be augmented with the following optional flags.

# Replace flag with a value from the table. You can use multiple flags together.
yarn run simpleAccount ... --flag
dryRunThis will go through the whole process of making a UserOperation, but will not call eth_sendUserOperation. It is useful for debugging purposes to see what the final UserOperation looks like.
withPaymasterThis will call pm_sponsorUserOperation on paymaster.rpcUrl with the UserOperation, EntryPoint, and paymaster.context. If successful, gas for this transaction will be paid for by the paymaster.
overrideBundlerRpcThis will allow you to route all bundler RPC method calls to a separate URL. The library userop.js uses a custom Provider to do this on the client.