Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18 or higher recommended

pnpm

Fast, disk space efficient package manager

MetaMask

Or another Web3 wallet for blockchain interactions

Git

For cloning the repository

​
Installing Prerequisites

Download and install Node.js from nodejs.org. We recommend using the LTS version.Verify installation:
node --version
# Should show v18.x.x or higher
MetaVault AI uses pnpm as its package manager. Install it globally:
npm install -g pnpm
Verify installation:
pnpm --version
# Should show 10.18.3 or higher
Install the MetaMask browser extension from metamask.io.You’ll need this to interact with the vault through the frontend.

​
Repository Structure

MetaVault AI is a monorepo containing three main packages: 
metavault-ai/
├── packages/
│   ├── contracts/       # Hardhat project with smart contracts
│   ├── frontend/        # Next.js web application
│   └── agents/          # AI agents built with ADK-TS
│       └── defi-portfolio/
├── package.json         # Root package with workspace scripts
└── pnpm-workspace.yaml  # pnpm workspace configuration
Each package can be developed independently, but they work together to form the complete MetaVault AI system.

​
Initial Setup

1

Clone the Repository

Clone the MetaVault AI repository to your local machine:
git clone <repository-url>
cd metavault-ai
2

Install Dependencies

Install all dependencies for the entire monorepo:
pnpm install
This command will:
  • Install root-level dependencies
  • Install dependencies for all packages (contracts, frontend, agents)
  • Set up workspace links between packages
The installation uses pnpm workspaces, which efficiently manages dependencies across the monorepo and creates symlinks between packages.
3

Configure Smart Contracts

Navigate to the contracts package and set up environment variables:
cd packages/contracts
cp .env.example .env
Edit .env and add your configuration:
# Deployer Wallet Private Key
PRIVATE_KEY=your_private_key_here

# INFURA API Key (optional for local development)
INFURA_KEY=your_infura_key
Never commit your .env file or share your private key. Use a test wallet with no real funds for development.
4

Configure AI Agents

Navigate to the agents package and set up environment variables:
cd packages/agents/defi-portfolio
cp .env.example .env
Edit .env and configure the following:
# ADK Configuration
ADK_DEBUG="false"

# OpenRouter API Key for LLM
OPEN_ROUTER_KEY=your_openrouter_key
LLM_MODEL=anthropic/claude-3.5-sonnet

# Server Ports
PORT=3001
CHAT_PORT=3002

# Telegram (optional)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHANNEL_ID=

# Blockchain
RPC_URL=http://127.0.0.1:8545
PRIVATE_KEY=your_private_key_here

# Contract addresses (will be filled after deployment)
VAULT_ADDRESS=
ROUTER_ADDRESS=
STRATEGY_LEVERAGE_ADDRESS=
STRATEGY_AAVE_ADDRESS=
LINK_ADDRESS=
MOCK_AAVE_POOL_ADDRESS=
You’ll need to obtain an OpenRouter API key from openrouter.ai to run the AI agents. Contract addresses will be populated after deploying the contracts.
5

Configure Frontend

Navigate to the frontend package and set up environment variables:
cd packages/frontend
cp .env.example .env.local
Edit .env.local:
# RPC
RPC_URL=http://127.0.0.1:8545
PRIVATE_KEY=your_private_key_here

# Agent API
AGENT_API_URL=http://localhost:3002

# Contract addresses (will be filled after deployment)
NEXT_PUBLIC_VAULT_ADDRESS=
NEXT_PUBLIC_ROUTER_ADDRESS=
NEXT_PUBLIC_STRATEGY_LEVERAGE_ADDRESS=
NEXT_PUBLIC_STRATEGY_AAVE_ADDRESS=
NEXT_PUBLIC_LINK_ADDRESS=
6

Compile Contracts

Return to the contracts directory and compile the smart contracts:
cd packages/contracts
pnpm hardhat compile
Or from the root:
pnpm contracts:compile
This will generate TypeScript types and compile all Solidity contracts.

​
Verify Installation

To verify your setup is complete, run these checks: 
cd packages/contracts
pnpm hardhat compile
Should compile without errors.

​
Tech Stack Overview

Smart Contracts

  • Solidity 0.8.28
  • Hardhat 2.26.5
  • OpenZeppelin 5.4.0

Frontend

  • Next.js 14
  • TypeScript 5.5
  • Wagmi & Viem
  • Tailwind CSS

AI Agents

  • ADK-TS 0.5.7
  • Express 5.2.1
  • TypeScript 5.9
  • node-cron 4.2.1

​
Common Issues

Make sure pnpm is installed globally:
npm install -g pnpm
Check your Node.js version:
node --version
Update to Node.js 18 or higher if needed.
Try cleaning and reinstalling:
cd packages/contracts
rm -rf cache artifacts node_modules
pnpm install
pnpm hardhat compile
If ports 3000, 3001, 3002, or 8545 are already in use, you can:
  • Change the ports in your .env files
  • Kill the process using the port
  • Use different port numbers in your configuration

​
Next Steps

Now that your environment is set up, you can:

Run Locally

Learn how to run the full stack locally

Testing Guide

Run tests and verify functionality

Build docs developers (and LLMs) love

Get started for freeTalk to us