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.

🎯 Problem Solved

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

1. Platform-Independent Links: Share a vault link through any messenger (KakaoTalk, Discord, Slack, WhatsApp)
2. Auto-Deduction: When participants accept, funds are automatically deposited to escrow smart contract
3. AI-Powered Verification: Upload receipt → GPT-4o Vision extracts total amount
4. HITL Approval: 60-second countdown for participants to reject expenses (auto-approve on timeout)
5. 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 + MySQL
• Frontend: Next.js 14 + Tailwind CSS
• State: MCP+ (Model Context Protocol)

🚀 Quick Start

Prerequisites

• 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)

DATABASE_URL="mysql://user:pass@localhost:3306/aegis_pay"
NEO_RPC_URL="https://testnet1.neo.org:20331"
VAULT_CONTRACT_HASH="0x..."
FRONTEND_URL="http://localhost:3000"

Agent (agent/.env if applicable)

OPENAI_API_KEY="sk-..."
NEO_PRIVATE_KEY="..."
DATABASE_URL="..."

🎯 MVP Scope (48-hour Hackathon)

Must Have ✅

• Backend API with MySQL
• Neo N3 smart contract (create, join, settle)
• Frontend vault creation UI
• Shareable link generation
• Receipt OCR with GPT-4o Vision
• 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

📚 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

1. MVP First: Ship working demo, polish later
2. 3-Layer Separation: Directives → Orchestration → Execution
3. Self-Annealing: When errors occur, fix + document + strengthen system
4. Platform Independence: Work across any messenger via links
5. 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