AgentVault

Agents with limits.

Hedera Hello Future Apex Hackathon 2026 — AI & Agents Track

Hackathon Submission

Project Description (100 words)

AgentVault is an agent-native execution fabric on Hedera that enables AI agents to safely interact with paid APIs and on-chain workflows using scoped, programmable permissions. Instead of sharing private keys, agents operate via session keys with explicit limits on protocols, assets, methods, and values. The platform includes a services marketplace, composable workflow engine, MCP server integration, and HCS-based audit trails. Smart contracts deployed on Hedera Testnet enforce session permissions on-chain, while HCS-10 provides agent identity registration. AgentVault delivers autonomous execution without autonomous risk — making Hedera a safe execution environment for AI agents.

Tech Stack

Repository Structure

agent_vault/
├── apps/
│   ├── web/                    # Next.js web application
│   │   ├── app/                # App router pages & API routes
│   │   ├── features/           # Feature modules (proxy, workflows, authorization)
│   │   ├── lib/                # Shared utilities (db, auth, crypto, session keys)
│   │   └── scripts/            # Database seed scripts
│   └── mcp-server/             # MCP server (stdio + HTTP transports)
│       └── src/
│           ├── stdio-bridge.ts # Stdio MCP bridge for Claude Code
│           ├── server.ts       # HTTP MCP server with OAuth
│           ├── tools/          # Tool registry & proxy tools
│           ├── hcs/            # HCS audit trail & agent identity
│           ├── payment/        # Payment signing via session keys
│           └── auth/           # OAuth 2.1 provider
├── hardhat/                    # Smart contract development
│   └── contracts/
│       └── AgentDelegator.sol  # Session key + smart account contract
└── packages/                   # Shared packages

What AgentVault Enables

• Services Marketplace — Browse, create, and monetize API proxies with usage-based pricing
• Composable Workflows — Chain API calls + on-chain actions into reusable automations
• MCP Server Integration — Expose tools to AI agents (Claude, ChatGPT) via Model Context Protocol
• Bounded Autonomy — Scoped session keys limit what agents can do (contracts, methods, values, time)
• Immutable Audit Trail — Every agent action logged to HCS for verifiable transparency
• Smart Account Upgrade — EOAs upgraded to smart accounts via ERC-7702 delegation

Core Architecture

flowchart LR
  AG["AI Agent\n(Claude / ChatGPT)"] --> MCP["MCP Server\nTool Discovery"]
  MCP --> AF["AgentVault\nAPI Proxies + Workflows\nPermission Enforcement"]:::good
  AF --> API["External APIs\nUsage-based payment"]
  AF --> HC["Hedera\nSmart Contracts"]:::good

  SK["Session Key\nScoped permissions"]:::good
  AG -. uses .-> SK
  SK -. authorizes .-> AF

  classDef good fill:#152a20,stroke:#4ade80,stroke-width:2px,color:#ffffff;

How It Works

1. User creates API services — Wrap any API with payment, variables, and encrypted credentials
2. User builds workflows — Combine HTTP calls + on-chain transactions with data flow
3. User configures MCP server — Select which tools to expose to AI agents
4. AI agent discovers tools — Claude/ChatGPT connects via MCP and sees available capabilities
5. Agent executes within bounds — Session key enforces what the agent can access
6. Actions are audited — HCS logs every tool invocation with timestamps

Setup & Testing Instructions

Prerequisites

• Node.js 20+
• pnpm 9+
• MetaMask browser extension
• Claude Code CLI (for MCP testing)

1. Clone & Install

git clone https://github.com/Jeremicarose/Agent-Vault.git
cd Agent-Vault
pnpm install

2. Environment Setup

cp apps/web/.env.example apps/web/.env.local
cp apps/mcp-server/.env.example apps/mcp-server/.env.local

Edit apps/web/.env.local:

DATABASE_URL=<your-postgresql-url>
NEXT_PUBLIC_REOWN_PROJECT_ID=<from-cloud.reown.com>
SESSION_SECRET=<openssl-rand-base64-32>

Edit apps/mcp-server/.env.local:

DATABASE_URL=<same-postgresql-url>
NEXT_APP_URL=http://localhost:3000

3. Database Setup

cd apps/web
pnpm db:push      # Create tables
pnpm db:seed      # Seed demo data (Token Price API + workflow)

4. Start the Application

# Terminal 1: Start the web app
pnpm dev:web

# Terminal 2: Start the MCP server (stdio mode for Claude Code)
pnpm dev:mcp

5. Test the Web Application

1. Open http://localhost:3000 — redirects to the Services Marketplace
2. Connect Wallet — Click "Connect Wallet", select MetaMask, sign the SIWX message
3. Browse Services — See Token Price API and Hedera Account Balance services
4. Try a Service — Click on Token Price API → "Make Request" → see live CoinGecko data
5. Create a Service — Go to Dashboard → Create a new API proxy
6. Build a Workflow — Go to Workflows → Create an automation chaining API + on-chain steps
7. Configure AI Agent — Go to Dashboard → AI Agent Hub → Create MCP server, assign tools

6. Test MCP Integration with Claude

# Add the AgentVault MCP server to Claude Code
claude mcp add agentvault -- \
  npx tsx apps/mcp-server/src/stdio-bridge.ts my-agent

# Start Claude Code
claude

# Ask Claude to use AgentVault tools:
> "Use the token_price_api tool to get the current price of HBAR"
> "Use hedera_account_balance to look up account 0.0.98"
> "Get the price of bitcoin and ethereum, then check account 0.0.1234"

Claude will discover the tools via MCP, call the AgentVault proxy, which fetches real data from CoinGecko and Hedera Mirror Node.

7. Test on Production

Visit the live deployment: https://agent-vault-web-jeremicaroses-projects.vercel.app

1. Connect MetaMask (Hedera Testnet)
2. Get testnet HBAR from https://portal.hedera.com/faucet
3. Browse and test services in the marketplace

Smart Contract

AgentDelegator — deployed on Hedera Testnet at 0x624f7c953dac044f3a38e7230c16f410cf7301d2

Features:

• ERC-7702 smart account upgrade (EOA → smart account)
• Session key management (grant, revoke, validate)
• Scoped permissions (allowed targets, selectors, time bounds)
• EIP-712 typed data for session signatures
• EIP-1271 signature validation for off-chain operations

Demo Scenario

In the demo, an AI agent (Claude) interacts with Hedera through AgentVault:

1. Discovers tools — Claude connects via MCP and sees token_price_api and hedera_account_balance
2. Fetches live data — Calls CoinGecko for HBAR price and Mirror Node for account balances
3. Reasons over results — Analyzes price data, calculates portfolio values
4. Executes workflows — Chains API calls with on-chain actions (price check → transfer)

All actions are bounded by session key permissions. No private keys are shared. Every action is logged to HCS.

Key Differentiators

License

MIT

Links

• Live Demo: https://agent-vault-web-jeremicaroses-projects.vercel.app
• Source Code: https://github.com/Jeremicarose/Agent-Vault
• Smart Contract: https://hashscan.io/testnet/contract/0x624f7c953dac044f3a38e7230c16f410cf7301d2