Starter Templates

The web3agent create command scaffolds a new project from a bundled template. Pick the template that matches your stack and you'll have a working blockchain-capable agent in minutes.

---

Creating a project

npx web3agent create

The command prompts you to choose a template and a project name, then scaffolds the directory structure, installs dependencies, and prints next steps.

To skip the prompt and pass arguments directly:

npx web3agent create my-agent --template mastra

---

Available templates

Vercel AI SDK

Template name: vercel-ai

The right choice if you're building with the Vercel AI SDK (ai package) and want to call web3agent tools from a streaming chat endpoint or a server action.

This template sets up:

• A Next.js app with a /api/chat route using streamText
• web3agent initialized as a runtime, with tools exposed to the AI SDK via convertToAISDKTools
• A minimal chat UI that streams responses
• Environment variable scaffolding for PRIVATE_KEY, CHAIN_ID, and your LLM provider key

// What the template wires up
import { createRuntime } from "web3agent/runtime";
import { streamText } from "ai";

const runtime = await createRuntime({ env: process.env });
const tools = convertToAISDKTools(runtime);

const result = streamText({
  model: openai("gpt-4o"),
  tools,
  messages,
});

When to use it: You're building a chat interface or API endpoint and want to use the Vercel AI SDK's streaming primitives. Good fit for Next.js apps.

---

Mastra

Template name: mastra

The right choice if you're building with Mastra, the TypeScript agent framework. This template creates a Mastra agent with web3agent tools pre-wired and a LibSQL memory backend.

This template sets up:

• A Mastra instance with a single agent
• web3agent SDK functions wrapped as Mastra tools
• LibSQL-backed persistent memory per user
• A simple CLI entrypoint to run the agent

// What the template wires up
import { Agent } from "@mastra/core";
import { Memory } from "@mastra/memory";
import { prepareSwapIntent, getSwapQuote } from "web3agent";

const agent = new Agent({
  name: "web3-agent",
  instructions: "You are a blockchain assistant...",
  model: anthropic("claude-sonnet-4-5"),
  memory: new Memory({ storage }),
  tools: {
    getSwapQuoteTool,
    prepareSwapIntentTool,
    // ... more tools
  },
});

When to use it: You want Mastra's agent loop, tool-calling paradigm, and memory system. Good fit for autonomous agents that need persistent context across sessions.

---

MCP host

Template name: mcp-host

The right choice if you're building a custom MCP host or a server that needs to spawn and manage a web3agent MCP server programmatically.

This template sets up:

• A Node.js server that spawns web3agent as a child process
• An MCP client that connects over stdio
• Tool discovery and invocation helpers
• Health check and restart logic

// What the template wires up
import { ProxyServer } from "web3agent/mcp";

const server = new ProxyServer({
  env: {
    CHAIN_ID: "8453",
    PRIVATE_KEY: process.env.PRIVATE_KEY,
  },
});

await server.start();

// Discover available tools
const tools = await server.listTools();

// Call a tool
const result = await server.callTool("resolve_token", {
  symbol: "USDC",
  chainId: 8453,
});

When to use it: You're building a platform that needs to manage web3agent instances programmatically, or you're integrating web3agent into a custom AI host that isn't Claude Code, Cursor, or Windsurf.

---

Template comparison

	Vercel AI SDK	Mastra	MCP host
Framework	Next.js + Vercel AI SDK	Mastra	Node.js (any)
Agent loop	Vercel AI SDK streamText	Mastra agent.generate()	Custom
Memory	None (add your own)	LibSQL (built-in)	None (add your own)
UI	Minimal chat UI included	CLI entrypoint	None
Best for	Chat apps, API endpoints	Autonomous agents	Custom hosts, platforms

---

npm create web3agent

The npm create web3agent entrypoint is a planned compatibility alias for npx web3agent create. It follows the convention of npm create vite, npm create next-app, and similar scaffolding tools.

# Planned — not yet available
npm create web3agent my-agent

Until this is available, use npx web3agent create directly.

---

After scaffolding

Every template prints the same next steps after scaffolding:

✓ Created my-agent/
✓ Installed dependencies

Next steps:
  cd my-agent
  cp .env.example .env
  # Edit .env with your PRIVATE_KEY and API keys
  npm run dev

The .env.example file in each template lists every environment variable the template uses, with comments explaining each one. Fill it in before running the dev server.