Public

scaffold-agent

Purpose

scaffold-agent is an interactive CLI that scaffolds monorepo projects for building onchain AI agents. It generates a full-stack project with smart contracts, a frontend, and agent infrastructure in one command.

Terminology: 1claw = 1claw.xyz (vault, Shroud LLM proxy, Intents API). OpenClaw (openclaw.ai) is a different product. @1claw/mcp = MCP server with 44 tools for vault secrets, Intents API, signing keys, treasury, and execution intents.

Prerequisites

• Node.js and npm — for npx scaffold-agent@latest and the generated workspace.
• just — installed separately (not an npm dependency). Generated repos use a root justfile for just chain, just deploy, just start, etc. Without just, run the equivalent npm run / npx scripts from the generated README.md.

Usage

npx scaffold-agent@latest
npx scaffold-agent@latest my-agent   # creates ./my-agent (skips project name prompt)
scaffold-agent --help                # full flag list; unknown flags error
scaffold-agent --version

CLI Flags

Scaffold Wizard (8 Steps)

1. Project name — alphanumeric, hyphens, underscores
2. Secrets management — 1Claw (HSM vault), Encrypted file (AES-256-GCM), or Plain .env
3. Agent identity — generate Ethereum wallet(s) for the agent (--swarm for multiple)
4. Ampersend SDK — optional @ampersend_ai/ampersend-sdk integration (signing key stored in vault or encrypted env; adds x402_paid_fetch tool)
5. The Graph — optional subgraph integration: none, mcp (IDE via @graphprotocol/subgraph-mcp), x402 (runtime agent tools), or both
6. LLM Provider — 1Claw (Shroud), Gemini, OpenAI, or Anthropic
7. Chain framework — Foundry, Hardhat, or None
8. App framework — Next.js, Vite, or Python (Google A2A)

What It Generates

project-root/
├── justfile                      # just chain / deploy / start / quickstart / doctor
├── scripts/
│   ├── secrets-crypto.mjs        # encrypt/decrypt .env.secrets.encrypted
│   ├── with-secrets.mjs          # prompt password, run deploy/start with env
│   ├── secret-add.mjs            # just env / enc / vault / reown
│   ├── deploy-foundry.mjs        # or deploy-hardhat.mjs
│   ├── generate-abi-types.mjs    # auto-gen TypeScript from contract ABIs
│   ├── generate-deployer.mjs     # create deployer wallet if missing (+ auto-fund)
│   ├── fund-deployer.mjs         # fund deployer + agents (incl. swarm roster)
│   ├── check-network.mjs         # validate targetNetwork has deployed contracts
│   ├── doctor.mjs                # just doctor — health check
│   └── swarm-agents.mjs          # just swarm — append wallets (Next/Vite)
├── packages/
│   ├── foundry/ (or hardhat/)    # Solidity contracts
│   └── nextjs/ (or vite/ or python/)
│       ├── public/agents.json    # swarm roster (addresses only; Next/Vite)
│       ├── app/
│       │   ├── layout.tsx            # root layout + shared Header nav
│       │   ├── page.tsx              # chat UI with suggested prompts
│       │   ├── identity/page.tsx     # ERC-8004 / Agent0 identity + register
│       │   ├── balances/page.tsx     # deployer + agent balances
│       │   ├── ens/page.tsx          # ENS resolution + registration links
│       │   ├── swarm/page.tsx        # swarm list + local keygen hints
│       │   ├── data/page.tsx         # The Graph subgraph explorer (when --graph enabled)
│       │   ├── debug/page.tsx        # deployed contracts (Next only)
│       │   └── api/
│       │       ├── chat/route.ts     # LLM streaming API (Vercel AI SDK)
│       │       ├── agent0/lookup/route.ts
│       │       └── graph/            # search + query routes (when --graph enabled)
│       ├── components/
│       │   ├── Header.tsx            # shared nav (Chat, Balances, ENS, Identity, Swarm, Data, Debug)
│       │   └── ui/                   # shadcn components
│       ├── lib/
│       │   ├── agent-onchain-tools.ts  # AI tools for wallet, ENS, contracts, intents, Graph
│       │   └── graph-client.ts       # The Graph gateway + x402 client (when --graph enabled)
│       ├── contracts/                # auto-generated ABI types
│       └── ...
├── .cursor/mcp.json              # 1Claw MCP for Cursor (when 1Claw is selected)
├── .mcp.json                     # 1Claw MCP for Claude Code (same server config)
├── .env                          # non-sensitive config (gitignored)
├── .env.secrets.encrypted        # AES-256-GCM encrypted keys (if chosen)
├── .gitignore
├── package.json                  # monorepo root (npm workspaces)
└── README.md

How an AI Agent Should Use This Tool

1. Determine the user's goal — Ask what kind of onchain AI agent they want to build. Identify the chain, the contract logic, and the agent's purpose.
2. Run the CLI — Execute npx scaffold-agent@latest in a clean directory. The CLI is interactive and will prompt for each configuration option. Use -y for defaults.
3. Select options — Choose the appropriate framework, LLM provider, and secret management based on the user's requirements.
4. Post-scaffold setup — After generation, the agent should:
   • cd into the project directory (npm install runs automatically during scaffolding)
   • Run just quickstart for one-command local setup (chain + fund + deploy + start), OR:
   • Run just chain to start a local blockchain (second terminal)
   • Run just fund to fund the deployer and agent wallets (100 ETH each)
   • Run just deploy to deploy contracts and generate ABI types
   • Run just start to launch the frontend or agent app
5. Validate — Run just doctor to health-check the environment, .env, 1Claw IDs, and package installs.
6. Iterate — Modify the generated agent logic in the packages/ directory.

All Just Recipes

Unified Network Model

Generated projects use a single source of truth for the active EVM network:

• scaffold.config.ts defines targetNetwork (e.g. "localhost", "base", "sepolia") and optional rpcOverrides.
• getActiveNetwork() resolves the full NetworkDefinition (chainId, RPC, block explorer) with overrides applied.
• AI agent tools (lib/agent-onchain-tools.ts) default chainId and chain parameters to the active network.
• ONECLAW_CHAIN_NAMES maps chainId → 1Claw slug for all 29 EVM mainnets + testnets, plus non-EVM chains.

Agent On-Chain Tools

Next.js and Vite projects include lib/agent-onchain-tools.ts — preset Vercel AI SDK tools wired into the chat route:

Always included:

• list_project_addresses — list agent + deployer addresses from .env (use before balance checks).
• get_wallet_balance — native + configured ERC-20 balances for an address (defaults to agent wallet).
• resolve_ens — resolve ENS names to addresses (and reverse lookup).
• lookup_erc8004_agents — search ERC-8004 / Agent0 registry for on-chain agent identities.
• list_deployed_contracts — enumerate addresses from deployedContracts.ts (hints active chain).
• contract_read — call any view/pure function via RPC using the deployed ABI (defaults to active network).

When 1Claw SDK is included:

• oneclaw_check_signing_balances — list HSM signing keys and their on-chain balances.
• oneclaw_intent_simulate — simulate a transaction via 1Claw Intents + Tenderly.
• oneclaw_intent_submit — submit a signed transaction intent to 1Claw's HSM/TEE (keys never in the model).
• oneclaw_intent_sign_only — sign a transaction without broadcasting (MEV protection, Flashbots, custom relayers).
• oneclaw_list_signing_keys — list the agent's HSM-backed signing keys (address, chain, status).
• oneclaw_list_transactions — list recent Intents API transactions for this agent.

When Ampersend is enabled:

• x402_paid_fetch — paid HTTP requests over x402.

When The Graph is enabled (--graph x402 or both):

• graph_search_subgraphs — search The Graph Network by keyword (e.g. uniswap, aave, ens).
• graph_subgraph_query — run GraphQL queries against a subgraph (API key or x402 USDC payment).

The 1Claw intent tools default the chain parameter to the active network's 1Claw slug via ONECLAW_CHAIN_NAMES — covering all 29 EVM mainnets, testnets, plus non-EVM chains (Bitcoin, Solana, XRP, Cardano, Tron).

The Graph Integration

--graph controls subgraph data access in generated projects:

Optional --graph-api-key or vault path api-keys/thegraph (GRAPH_API_KEY) — some subgraphs work with an API key; Substreams-powered subgraphs may require x402 USDC payment per query. If a query returns 402, search for an alternate subgraph ID via graph_search_subgraphs.

1Claw MCP Integration

When 1Claw is selected, the scaffold generates .cursor/mcp.json (Cursor) and .mcp.json (Claude Code) with the @1claw/mcp server pre-configured. This gives AI agents access to 44 MCP tools: vault secrets, Intents API (simulate, submit, sign), signing key management, treasury proposals, and execution intents. Only ONECLAW_AGENT_API_KEY is required — agent ID and vault are auto-discovered.

HSM Signing Key Provisioning

When 1Claw Intents is enabled (--oneclaw-intents), the CLI provisions HSM signing keys via the 1Claw API for each chain selected. Interactive runs show a multi-select; non-interactive runs use --oneclaw-signing-chains (comma-separated: ethereum, bitcoin, solana, xrp, cardano, tron; default ethereum). Keys are generated inside the HSM — never exposed. The CLI prints each address with testnet faucet links and dashboard deep links.

Intents API — Multi-Chain Signing

The 1Claw Intents API supports HSM/TEE transaction signing across:

• 29 EVM mainnets: Ethereum, Base, Optimism, Arbitrum One, Polygon, Avalanche, BNB, zkSync Era, Linea, Scroll, Mantle, Blast, Gnosis, Fantom, Celo, Aurora, Metis, Moonbeam, Cronos, Sonic, World Chain, Polygon zkEVM, Sei, Kaia, Mode, Arbitrum Nova, Berachain, Taiko, Zora
• EVM testnets: Sepolia, Base Sepolia, Holesky, Optimism Sepolia, Arbitrum Sepolia, Polygon Amoy, and more
• Non-EVM chains: Bitcoin, Solana, XRP, Cardano, Tron

Per-agent guardrails: allowed chains, recipient allowlists, per-tx value caps, daily spending limits.

Swarm Mode

--swarm <n> (1–64) generates multiple agent wallets:

• First wallet stays AGENT_ADDRESS / AGENT_PRIVATE_KEY; extras go in encrypted SWARM_AGENT_KEYS_JSON.
• Public roster at packages/*/public/agents.json (addresses only).
• Generated Next/Vite apps include lib/agent-swarm.tsx, a header agent picker, and a /swarm page.
• Post-scaffold: just swarm agents=N to append more wallets.

Config File (agent.json)

• --from-config <file> merges JSON into the wizard; CLI flags override the file.
• Shape: project / name, swarm, agents (id → preset label), optional extra (written to agent.config.extra.json), optional options with CLI-like keys.
• --dump-config prints merged JSON (no scaffold). --dump-config-out <file> writes to a file. Passwords and API keys are omitted so the file is safe to share.

LLM Providers

Shroud Upstreams and Default Models

Direct LLM Defaults (not Shroud)

1Claw Integration

When you choose 1Claw for secrets:

• Authenticates with ONECLAW_API_KEY
• Creates a vault; writes ONECLAW_VAULT_ID into .env
• Stores deployer private key in vault (not on disk)
• If agent identity is generated, stores it and registers the agent
• If picking 1Claw as LLM, registers a Shroud agent and writes ONECLAW_AGENT_ID + ONECLAW_AGENT_API_KEY
• If Intents enabled, provisions HSM signing keys for selected chains

ONECLAW_AGENT_ID is a UUID, not an Ethereum 0x… address. Chat uses X-Shroud-Agent-Key, not Authorization: Bearer for Shroud.

Key Architecture

• Uses just as the task runner (https://just.systems)
• Monorepo managed with npm workspaces
• Agent wallet auto-generated and funded on local/test networks
• Smart contract ABIs auto-exported to frontend (Scaffold-ETH 2 pattern via deployedContracts.ts)
• Chat routes use the Vercel AI SDK for LLM streaming
• 1Claw Shroud gateway: 9 upstream providers, token billing or BYOK
• @1claw/mcp: 44 MCP tools auto-configured for Cursor and Claude Code
• Intents API: HSM/TEE signing across 29+ EVM chains + Bitcoin, Solana, XRP, Cardano, Tron
• Built on Scaffold-ETH 2, Scaffold UI, RainbowKit, wagmi, and viem
• 1Claw-inspired dark theme (crimson accent, Inter font, sticky glass header)
• Shared Header nav (Chat, Balances, ENS, Identity, Swarm, Data, Debug)
• Suggested prompts on empty chat state
• The Graph subgraph integration (--graph mcp|x402|both) with /data page and agent tools
• Burner wallet for local dev via burner-connector
• Pinned @1claw/sdk 0.41.2 in generated projects (when 1Claw is selected)

Key Environment Variables

Ethereum Development Reference

For best practices on building for Ethereum — including Solidity patterns, contract deployment, testing, and frontend integration — agents should also read:

https://ethskills.com/SKILL.md

Repository

https://github.com/1clawAI/scaffold-agent