SDK & CLI

contract.dev offers both a CLI and TypeScript SDK for working with Stagenets.

Use the CLI for project-level tasks:

Init Workspaces from a Hardhat or Foundry project’s contracts.
Generate and fund wallets for use on your Stagenet.
Track state over time — balances, ERC20 holdings, storage slots, and view function results.

Use the SDK to script Stagenet actions:

Install

The contract.dev npm package contains both the CLI and the SDK.


npm install contract.dev

Setup

Create a contract.dev.js file in your project root:


npx contract.dev init

Add your Stagenet RPC URL:


/** @type {import('contract.dev').Config} */
module.exports = {
  rpcUrl: "<YOUR_STAGENET_RPC_URL>",
};

Use contract.dev.cjs instead if your package.json has "type": "module".

Use the CLI

Run CLI commands from your project root:


# Init Workspaces from your Hardhat/Foundry project's contracts
contract.dev init-workspaces
 
# Generate a funded wallet on your Stagenet
contract.dev generate-wallet
 
# Track a balance, ERC20, storage slot, or view function over time
contract.dev track add balance 0x1111111111111111111111111111111111111111 --name "alice ETH"

Use the SDK

Create a Stagenet client in your script:


import { createStagenet } from "contract.dev";
 
const stagenet = createStagenet("<YOUR_STAGENET_RPC_URL>");

Or load the RPC URL from contract.dev.js:


const stagenet = createStagenet();

The no-argument form reads from the filesystem, so it is Node-only. Pass the RPC URL explicitly in browsers or edge runtimes.

Then interact with your Stagenet:


// Mint 1 ETH to an address
await stagenet.addBalance(
  "0x1111111111111111111111111111111111111111",
  10n ** 18n,
);
 
// Impersonate an account
await stagenet.impersonateAccount(
  "0x28C6c06298d514Db089934071355E5743bf21d60",
);
 
// Override a nonce
await stagenet.setNonce(
  "0x1111111111111111111111111111111111111111",
  42,
);