Aegis Pay - The Autonomous Social Treasurer

Seoul Bowl Hackathon 2025 | Track: Autonomous Finance & FinTech

An autonomous financial agent for group expense management built with AI + Web3. Aegis Pay acts as a decentralized treasurer that automates fund collection, expense verification, and settlement using SpoonOS and Neo N3 blockchain.

🌐 Live Demo

Frontend: https://frontend-three-ashen-38.vercel.app
Backend API: https://aegis-pay-backend-872951985428.asia-northeast3.run.app
Agent Server: https://aegis-pay-agent-872951985428.asia-northeast3.run.app
Smart Contract: 0x8f616d5ead7dbd85ccea2f61c2fff36bea53ba6b (Neo N3 TestNet)

🎯 Problem Solved

Traditional bill-splitting apps only calculate debt - they don't collect money or execute payments. Aegis Pay automates the entire flow:

Platform-Independent Links: Share a vault link through any messenger (KakaoTalk, Discord, Slack, WhatsApp)
Auto-Deduction: When participants accept, funds are automatically deposited to escrow smart contract
AI-Powered Verification: Upload receipt → GPT-4o Vision extracts total amount
HITL Approval: 60-second countdown for participants to reject expenses (auto-approve on timeout)
Autonomous Settlement: Agent calculates optimal payouts and executes blockchain transfers

🏗️ Architecture

3-Layer System

┌─────────────────────────────────────────────────────────┐
│  Layer 1: Directives (What to do)                       │
│  - Natural language SOPs in directives/                 │
│  - Define goals, inputs, outputs for each workflow      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 2: Orchestration (Decision making)               │
│  - SpoonOS SCDF graph-based workflows                   │
│  - ReAct agent pattern                                  │
│  - HITL interrupts for approval flows                   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 3: Execution (Deterministic)                     │
│  - Python scripts (execution/)                          │
│  - Neo N3 smart contracts (contracts/)                  │
│  - Express.js backend (backend/)                        │
└─────────────────────────────────────────────────────────┘

Tech Stack

Agentic Runtime: SpoonOS (SCDF framework)
AI: GPT-4o Vision (OCR only)
Blockchain: Neo N3 TestNet (smart contracts)
Backend: Express.js + Prisma + SQLite
Frontend: Next.js 14 + Tailwind CSS + shadcn/ui
State: MCP+ (Model Context Protocol)
Deployment:
- Frontend: Vercel
- Backend & Agent: GCP Cloud Run
- Database: SQLite (ephemeral)
Infrastructure: Docker, Cloud Build

🚀 Quick Start

Try Live Demo First!

Before setting up locally, try the live demo:

Visit: https://frontend-three-ashen-38.vercel.app
Connect NeoLine Wallet (Neo N3 TestNet)
Create a Vault or join an existing one
Upload Receipt to test OCR
Share Link via any messenger

Prerequisites for Local Development

Docker & Docker Compose
Node.js 18+
Python 3.10+
Neo N3 wallet with TestNet GAS

1. Clone & Setup

git clone <repo-url>
cd aegis-pay

# Run automated setup
chmod +x scripts/setup.sh
./scripts/setup.sh

This will:

Start MySQL via Docker
Install backend dependencies
Run Prisma migrations

2. Start Backend

cd backend
npm run dev

Backend API runs on http://localhost:4000

3. Deploy Smart Contract

cd contracts

# Compile contract
neo3-boa compile vault.py

# Deploy to Neo N3 TestNet (see contracts/README.md)
# Update backend/.env with contract hash

4. Set Up Agent (Optional)

cd agent  # If agent folder exists
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows
pip install -r requirements.txt

python main.py  # Start agent server

5. Start Frontend

cd frontend  # If frontend folder exists
npm install
npm run dev

Frontend runs on http://localhost:3000

📁 Project Structure

aegis-pay/
├── backend/              # Express.js API + Prisma
│   ├── src/
│   │   ├── server.js    # Entry point
│   │   ├── routes/      # API routes
│   │   ├── services/    # Business logic
│   │   └── lib/         # Utilities
│   ├── prisma/
│   │   └── schema.prisma
│   └── package.json
│
├── contracts/            # Neo N3 smart contracts
│   ├── vault.py         # Main escrow contract
│   └── README.md
│
├── directives/           # Agent SOPs (Layer 1)
│   ├── vault_creation.md
│   ├── ocr_receipt.md
│   ├── hitl_approval.md
│   └── settlement.md
│
├── execution/            # Deterministic scripts (Layer 3)
│   ├── ocr_extract.py
│   ├── calculate_split.py
│   ├── neo_deploy.py
│   └── neo_transfer.py
│
├── src/                  # Frontend components
│   ├── components/
│   ├── lib/
│   └── styles/
│
├── docs/                 # Documentation
│   ├── PRD.md
│   ├── ARCHITECTURE.md
│   ├── SMART_CONTRACT.md
│   └── SPOONOS_WORKFLOW.md
│
├── scripts/
│   └── setup.sh         # Quick setup script
│
├── docker-compose.yml   # MySQL container
├── CLAUDE.md            # Agent instructions
└── README.md            # This file

🔧 Development Workflow

Backend Development

cd backend

# Development with hot reload
npm run dev

# Database management
npm run prisma:studio    # Visual DB editor
npm run prisma:migrate   # Create new migration

# Testing
curl http://localhost:4000/health

Smart Contract Development

cd contracts

# Compile
neo3-boa compile vault.py

# Deploy to TestNet
# See contracts/README.md for deployment options

# Test
python test_vault.py

Frontend Development

cd frontend

# Development server
npm run dev

# Build for production
npm run build

# Type checking
npm run type-check

🌐 API Endpoints

Health Check

GET /health

Vaults

POST   /api/vaults              # Create vault
GET    /api/vaults/:id          # Get vault details
POST   /api/vaults/:id/join     # Join vault
POST   /api/vaults/:id/expenses # Upload expense receipt
POST   /api/vaults/:id/close    # Close vault and settle

🧪 Testing

Backend

cd backend
curl -X POST http://localhost:4000/api/vaults \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Vault",
    "target_participants": 3,
    "amount_per_person": 10,
    "created_by": "NQtest123..."
  }'

Smart Contract

cd contracts
python test_vault.py

# Or use neo-express
neoxp contract invoke <hash> create_vault [params...]

📊 Database Schema

See backend/prisma/schema.prisma for full schema. Key models:

Vault: Main vault entity
Participant: Users who joined vault
Expense: Receipt uploads with OCR data
Transaction: Blockchain transaction records

🔐 Environment Variables

Backend (`backend/.env`)

# Local Development
DATABASE_URL="mysql://root:password@localhost:3306/aegis_pay"
NEO_NETWORK="TestNet"
NEO_RPC_URL="https://testnet1.neo.coz.io:443"
NEO_CONTRACT_HASH="0x8f616d5ead7dbd85ccea2f61c2fff36bea53ba6b"
NEO_WALLET_WIF="YOUR_WIF_KEY"
NEO_WALLET_PASSWORD="YOUR_PASSWORD"
AGENT_URL="http://localhost:8000"
FRONTEND_URL="http://localhost:3000"

Agent (`agent/.env`)

OPENAI_API_KEY="sk-proj-..."
OPENAI_MODEL="gpt-4o-2024-08-06"
SPOONOS_API_KEY="sk-or-v1-..."
BACKEND_URL="http://localhost:4000"
NEO_RPC_URL="https://testnet1.neo.coz.io:443"
NEO_WALLET_WIF="YOUR_WIF_KEY"
NEO_WALLET_PASSWORD="YOUR_PASSWORD"
NEO_CONTRACT_HASH="0x8f616d5ead7dbd85ccea2f61c2fff36bea53ba6b"
NEO_NETWORK="TestNet"
AGENT_HOST="0.0.0.0"
AGENT_PORT="8000"
HITL_APPROVAL_TIMEOUT="60"
POLLING_INTERVAL="5"

Frontend (`frontend/.env.local`)

NEXT_PUBLIC_API_URL="http://localhost:4000"
NEXT_PUBLIC_AGENT_URL="http://localhost:8000"
NEXT_PUBLIC_AGENT_WS_URL="ws://localhost:8000/ws"
NEXT_PUBLIC_NEO_NETWORK="TestNet"
NEXT_PUBLIC_NEO_RPC_URL="https://testnet1.neo.coz.io:443"
NEXT_PUBLIC_VAULT_CONTRACT_HASH="0x8f616d5ead7dbd85ccea2f61c2fff36bea53ba6b"

Production (Cloud Run & Vercel)

All services are deployed with production environment variables configured in:

Backend: Cloud Run environment variables
Agent: Cloud Run environment variables
Frontend: Vercel environment variables

🎯 MVP Scope (48-hour Hackathon)

Must Have ✅

Backend API with SQLite (deployed on Cloud Run)
Neo N3 smart contract (deployed on TestNet)
Frontend vault creation UI (deployed on Vercel)
Shareable link generation
Receipt OCR with GPT-4o Vision
Auto-deduction on vault join
SpoonOS agent integration (deployed on Cloud Run)
HITL approval flow
Automated settlement

Nice to Have

SpoonOS agent integration
WebSocket real-time updates
Email notifications
Receipt search with BeVec

Out of Scope

Mobile app
Multi-vault management
Mainnet deployment
Advanced analytics

🚀 Deployment

All services are deployed and running:

Frontend (Vercel)

URL: https://frontend-three-ashen-38.vercel.app
Framework: Next.js 14
Region: Washington, D.C. (iad1)

Backend (GCP Cloud Run)

URL: https://aegis-pay-backend-872951985428.asia-northeast3.run.app
Region: asia-northeast3 (Seoul)
Database: SQLite (/tmp/aegis_pay.db)
Auto-scaling: 0-10 instances

Agent (GCP Cloud Run)

URL: https://aegis-pay-agent-872951985428.asia-northeast3.run.app
Region: asia-northeast3 (Seoul)
Features: OCR, HITL, Settlement workflows
Auto-scaling: 0-10 instances

Smart Contract (Neo N3 TestNet)

Hash: 0x8f616d5ead7dbd85ccea2f61c2fff36bea53ba6b
Network: TestNet
RPC: https://testnet1.neo.coz.io:443

📚 Documentation

PRD - Product Requirements
Architecture - System Design
Smart Contracts - Contract Specs
SpoonOS Workflows - Agent Implementation
UI Components - Frontend Design
API Conventions - API Standards

🚨 Troubleshooting

MySQL Connection Issues

# Check if container is running
docker ps

# View logs
docker logs aegis-pay-mysql

# Restart
docker-compose restart mysql

Prisma Issues

# Regenerate client
cd backend
npm run prisma:generate

# Reset database (⚠️ deletes all data)
npx prisma migrate reset

Contract Deployment

# Check TestNet GAS balance
# Get more from: https://neowish.ngd.network/

# Verify RPC endpoint
curl https://testnet1.neo.org:20331

🎨 Design Principles

MVP First: Ship working demo, polish later
3-Layer Separation: Directives → Orchestration → Execution
Self-Annealing: When errors occur, fix + document + strengthen system
Platform Independence: Work across any messenger via links
HITL by Default: Human approval required, auto-timeout as fallback

🤝 Contributing

This is a hackathon project. Contributions welcome after Seoul Bowl 2025!

📄 License

MIT

👥 Team

Aegis Pay Team - Seoul Bowl Hackathon 2025

Built with: SpoonOS | Neo N3 | GPT-4o | Next.js | Express.js

Hackathon Deadline: December 21, 2025, 23:59 KST

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
agent		agent
backend		backend
contracts		contracts
directives		directives
docs		docs
execution		execution
frontend		frontend
scripts		scripts
src		src
.env.production.example		.env.production.example
.gitignore		.gitignore
API_CONVENTIONS.md		API_CONVENTIONS.md
ARCHITECTURE.md		ARCHITECTURE.md
DEMO_CHECKLIST.md		DEMO_CHECKLIST.md
DEPLOYMENT.md		DEPLOYMENT.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
PRD.md		PRD.md
PROJECT_STATUS.md		PROJECT_STATUS.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
README_DEPLOYMENT.md		README_DEPLOYMENT.md
SMART_CONTRACT.md		SMART_CONTRACT.md
SPOONOS_WORKFLOW.md		SPOONOS_WORKFLOW.md
UI_COMPONENTS.md		UI_COMPONENTS.md
claude.md		claude.md
docker-compose.yml		docker-compose.yml
my_first_agent.py		my_first_agent.py
tailwind.config.js		tailwind.config.js

AIHackatonA5/aegis-pay

Folders and files

Latest commit

History

Repository files navigation