Agent Vault
AgentVault β agent-native execution fabric for Hedera
Ask AI about Agent Vault
Powered by Claude Β· Grounded in docs
I know everything about Agent Vault. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AgentVault
Agents with limits.
Hedera Hello Future Apex Hackathon 2026 β AI & Agents Track
Hackathon Submission
| Live Demo | agent-vault-web.vercel.app |
| Demo Video | YouTube |
| Smart Contract | 0x624f7c953dac044f3a38e7230c16f410cf7301d2 |
| Track | AI & Agents |
| Bounty | Hashgraph Online |
| Developer | Jeremi Carose |
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
| Layer | Technology |
|---|---|
| Blockchain | Hedera Testnet (EVM-compatible), Solidity smart contracts |
| Smart Contracts | AgentDelegator (ERC-7702 smart accounts, session keys), deployed via Hardhat |
| Consensus | Hedera Consensus Service (HCS) for immutable audit trails, HCS-10 agent identity |
| Frontend | Next.js 16, React 19, TailwindCSS, shadcn/ui |
| Backend | Next.js API routes, Drizzle ORM, PostgreSQL (Neon) |
| Wallet | Reown AppKit + SIWX (Sign-In With eXtendable), MetaMask |
| AI Integration | Model Context Protocol (MCP) server, stdio transport |
| Cryptography | RSA+AES hybrid encryption for API credentials, EIP-712 typed signatures |
| Deployment | Vercel (web app), pnpm monorepo |
| Languages | TypeScript, Solidity |
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
- User creates API services β Wrap any API with payment, variables, and encrypted credentials
- User builds workflows β Combine HTTP calls + on-chain transactions with data flow
- User configures MCP server β Select which tools to expose to AI agents
- AI agent discovers tools β Claude/ChatGPT connects via MCP and sees available capabilities
- Agent executes within bounds β Session key enforces what the agent can access
- 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
- Open http://localhost:3000 β redirects to the Services Marketplace
- Connect Wallet β Click "Connect Wallet", select MetaMask, sign the SIWX message
- Browse Services β See Token Price API and Hedera Account Balance services
- Try a Service β Click on Token Price API β "Make Request" β see live CoinGecko data
- Create a Service β Go to Dashboard β Create a new API proxy
- Build a Workflow β Go to Workflows β Create an automation chaining API + on-chain steps
- 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
- Connect MetaMask (Hedera Testnet)
- Get testnet HBAR from https://portal.hedera.com/faucet
- 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:
- Discovers tools β Claude connects via MCP and sees
token_price_apiandhedera_account_balance - Fetches live data β Calls CoinGecko for HBAR price and Mirror Node for account balances
- Reasons over results β Analyzes price data, calculates portfolio values
- 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
| Feature | Description |
|---|---|
| Zero Key Sharing | Agents use scoped session keys, never the owner's private key |
| Composable Execution | Mix HTTP APIs + smart contract calls in single workflows |
| MCP Native | First-class Model Context Protocol support for Claude & ChatGPT |
| HCS Audit Trail | Immutable, verifiable log of every agent action on Hedera |
| Usage-Based Payments | APIs priced per-request with HTS-compatible settlement |
| Visual Builder | No-code workflow editor with drag-and-drop step configuration |
License
MIT
