AGENT VAULT

An AI-assisted on-chain wallet that makes crypto transactions safer, clearer, and verifiable through intelligent explanations, policy-based security, and user-controlled execution.

Comment

Inspiration

A blockchain transaction can be irreversible, and an AI-generated recommendation is not enough to make a financial action safe. Users need to understand what they are authorizing, while the application must enforce rules independently of what an AI model says.

That problem inspired us to build Agent Vault, a policy-controlled, AI-assisted on-chain wallet. We wanted to combine plain-language transaction explanations with explicit spending limits, recipient validation, user-controlled signing, and blockchain verification.

Our project addresses Topic F — Agent Wallet (Autonomous On-chain Wallet) under the competition theme AI as a Financial Participant.

What it does

Agent Vault provides a controlled workflow for preparing and executing native ETH transfers on the Sepolia testnet.

  • MetaMask integration: Connect a wallet and authenticate ownership through a signed challenge.
  • AI-assisted explanations: An optional Claude API integration generates plain-language explanations of proposed transactions.
  • Deterministic policy enforcement: Check approved recipients and enforce per-transaction and daily spending limits.
  • Transaction validation: Check wallet balance, estimate gas fees, and simulate the proposed transaction before approval.
  • User-controlled execution: Let the user review and sign the transaction through MetaMask. The backend does not hold the user's wallet private key.
  • On-chain verification and audit history: Check transaction details and receipts through EVM JSON-RPC and maintain searchable application audit records.

The workflow is straightforward: connect → propose → validate → review and sign → verify → audit.

The current implementation focuses on native ETH transfers on Sepolia. It is a human-in-the-loop wallet prototype; fully autonomous goal planning and multi-step transaction execution remain future work.

How we built it

We built Agent Vault with a React and TypeScript frontend and a Python backend, separating the user interface, transaction validation, wallet authorization, and blockchain interaction.

Frontend

  • TypeScript for typed application logic.
  • React for UI components and application state.
  • Vite for development and production builds.
  • CSS for styling and layout.
  • lucide-react for interface icons.
  • MetaMask's browser provider for wallet connection and transaction approval.

Backend

  • Python for application and transaction-processing logic.
  • FastAPI for API endpoints.
  • Uvicorn for serving the ASGI application.
  • SQLite for application audit records.
  • Python cryptographic libraries for the cryptographic operations used by the backend and tests.

Blockchain integration

  • EVM-compatible JSON-RPC for retrieving balances, simulating transactions, estimating gas, and checking transactions and receipts.
  • Sepolia testnet for the current native ETH transfer workflow.
  • MetaMask / EIP-1193 for browser-wallet communication.
  • EIP-191 signed-message authentication for verifying wallet ownership through a signed challenge.

AI integration

  • Anthropic Claude API (optional) for generating explanatory text about proposed transactions. The model does not authorize transactions or override backend policy checks.

The backend validates transaction proposals before the user proceeds to MetaMask approval. After broadcast, it checks the transaction and receipt and records the outcome in the audit history. Because the current workflow uses native ETH transfers, it does not require a custom Solidity smart contract.

Challenges we ran into

Separating AI assistance from transaction authorization. An AI response can explain a transaction, but it should not decide whether that transaction satisfies security requirements. We kept the explanation layer separate from deterministic backend validation.

Coordinating the transaction lifecycle. Wallet authentication, proposal creation, policy checks, simulation, signing, broadcasting, and confirmation are separate stages. We designed the workflow so that passing one stage is not treated as proof that every later stage succeeded.

Handling duplicate and stale proposals. Transaction approval workflows need protection against the reuse of expired or previously consumed requests. The implementation includes short-lived, single-use proposal intents and duplicate/replay protections.

Testing without overstating reliability. Automated tests and a successful frontend build are necessary, but they do not prove that the complete application works in a live deployment. We distinguish these checks from live end-to-end verification and a full independent security audit.

Accomplishments that we're proud of

  • Built a full-stack prototype combining React, TypeScript, Python, and FastAPI.
  • Implemented MetaMask connection and signed-challenge wallet authentication.
  • Integrated transaction policy checks, including recipient allowlists and spending limits.
  • Added transaction simulation, gas estimation, and balance validation to the proposal workflow.
  • Kept wallet signing under user control instead of placing private keys on the backend.
  • Implemented transaction verification and searchable application audit history.
  • Integrated optional AI-generated transaction explanations without making the language model the security authority.

The frontend production build completed successfully, and the backend automated test suite reported 7 passed, 1 warning. These results demonstrate successful build and test runs; a complete live end-to-end deployment has not yet been verified.

What we learned

  • AI-generated explanations and deterministic financial controls serve different purposes. They should be separated rather than treated as interchangeable.
  • Wallet ownership verification requires a proper signed-message flow, not just a connected wallet address.
  • Transaction construction, simulation, gas estimation, signing, broadcasting, and receipt verification must be treated as distinct stages.
  • User-controlled signing provides an important authorization boundary for a wallet prototype that is not yet ready for unrestricted autonomous execution.
  • Passing automated tests is only one part of verification; live transaction evidence, deployment testing, and security assessment remain important.

What's next for AGENT VAULT

Our next steps are focused on completing the transaction workflow and moving toward bounded autonomy.

  1. Complete an end-to-end Sepolia transaction demonstration and document its real, verifiable transaction hash.
  2. Finalize the security self-assessment, known-risk list, and explicit permission boundaries.
  3. Improve deployment reliability and plan persistent database storage beyond the current SQLite prototype.
  4. Develop goal-driven agent planning so the application can interpret a user's intent and prepare structured transaction proposals within explicit permissions.
  5. Expand to token transfers or additional EVM networks only after implementing and testing the necessary controls.
  6. Conduct a comprehensive security review before considering use with real funds.

Our goal is to build on the current prototype toward an agent wallet that can help users complete financial tasks while keeping permissions explicit, decisions understandable, and execution verifiable.

Built With

Share this project:

Updates