AutoPilot

AI-Powered Financial Automation on the Stellar Network

🚀 Live Demo | ▶️ Demo Video | 🐛 Report a Bug | 💬 Discussions

⚠️ This project currently runs on the Stellar Testnet only. All transactions use test XLM with no real monetary value. See Contributing to run it locally.

📖 Table of Contents

What is AutoPilot?
Features
Architecture
Tech Stack
Blockchain Details
Screenshots
Quick Start
File Structure
Testing
Error Handling
Roadmap
Contributing
Security
License
Contributors

💡 What is AutoPilot?

Managing personal finances — specifically, consistently saving and investing — is a manual, emotional, and often forgotten task. Traditional banking apps offer basic "auto-transfers" but lack dynamic intelligence (e.g., "save 10% only if I receive a payment over $50").

AutoPilot bridges natural language AI with the speed and low cost of the Stellar blockchain. Users simply tell the AI what they want:

"Save 15% of every incoming XLM payment into my savings vault."

…and the AutoPilot engine constantly monitors their Stellar wallet, executing those rules autonomously and instantly — no manual steps needed.

Real-World Example

A freelancer gets paid sporadically in XLM on Stellar. Instead of manually moving money every time they get paid, AutoPilot automatically calculates 15% of each payment and instantly sweeps it into a secure, on-chain Vault account. Zero effort. Every time.

✨ Features

Feature	Description
🗣️ Natural Language Rules	Type rules in plain English — the AI translates them into executable financial logic.
🏦 Automated On-Chain Vaults	Instantly create isolated Stellar accounts for savings and investments.
📡 Live Blockchain Monitoring	The engine watches your account via Horizon API and triggers rules the moment a payment occurs.
🔒 AES-256-GCM Encryption	Vault private keys are encrypted at rest using bank-grade encryption.
🎯 Goal Tracking	Set financial goals (e.g., "Emergency Fund") and link them to automation rules for automatic progress.
🤖 AI Financial Coach	Chat with an AI coach to get rule suggestions based on your financial situation.
📊 Dynamic Dashboard	Real-time Stellar balances and automated transaction history.
🛡️ Spending Limits	Daily and weekly limits prevent automation from over-spending.

🏗️ Architecture

flowchart LR
    UI[Next.js Frontend] <-->|REST API / JWT| API[Fastify Backend]

    subgraph AutoPilot Backend
    API <--> AI[Groq AI Engine]
    API <--> DB[(PostgreSQL)]
    DB --> Engine[Rule Engine / Horizon Stream]
    end

    Engine <-->|Stellar SDK| Horizon[Stellar Horizon API]
    Horizon <--> Blockchain[(Stellar Testnet)]

User Flow

sequenceDiagram
    participant User
    participant AI Coach
    participant Engine
    participant Stellar Network

    User->>AI Coach: "Save 10% of incoming payments"
    AI Coach-->>Engine: JSON Rule (Trigger: Incoming, Action: Save, 10%)
    Engine->>Engine: Persist Rule to Database

    Note over Stellar Network, Engine: Sometime later...
    Stellar Network-->>Engine: Event: User received 100 XLM
    Engine->>Engine: Match Rule → Calculate 10 XLM
    Engine->>Stellar Network: Sign & Submit Tx → Vault
    Stellar Network-->>User: Vault Balance +10 XLM ✅

🛠️ Tech Stack

Category	Technology	Purpose
Frontend	Next.js 14, Tailwind CSS, TypeScript	Fast, responsive UI with Freighter wallet integration
Backend	Fastify, Node.js, TypeScript	High-performance API + background rule engine
Database	PostgreSQL (Neon)	Stores users, encrypted vault keys, rules, goals
Blockchain	Stellar SDK, Horizon API	Account creation, payments, trustlines on Stellar
Smart Contract	Soroban (Rust, `soroban-sdk`)	On-chain `AutopilotVault` contract for fund custody
AI Engine	Groq (Llama-3.3-70b / Qwen3)	Parses natural language rules into structured JSON
Queue	BullMQ + Redis (Upstash)	Reliable background job processing for rule execution
Security	AES-256-GCM, JWT	Encrypted vault keys; secure session management

⛓️ Blockchain Details

AutoPilot leverages Stellar's native capabilities and a Soroban smart contract for on-chain transparency.

Engine Architecture

Engine Account: The backend maintains a funded "Engine" Stellar keypair (AUTOPILOT_PUBLIC_KEY). This account orchestrates all automated transactions.
Vault Creation: When a user creates a Vault, a brand-new Stellar keypair is generated. The Engine funds it with the minimum XLM reserve (2.5 XLM) via a createAccount operation.
Key Security: The Vault's private key is encrypted using AES-256-GCM before being stored in PostgreSQL. It is only decrypted in-memory when a transaction needs to be signed.
Transaction Execution: The Horizon API SSE stream monitors the user's wallet. When a payment matches a rule, the engine signs and submits a transaction to the user's Vault.

Testnet Deployment

Component	Value	Explorer
Soroban Contract ID	`CACYX7GWKABSUFUF5MV5UVRH62F6A2D2SUSAHVC4FTIIKARTIBVUW6BP`	Stellar Lab
Contract Deploy Tx	`d3ad5ecb5401e327...`	Stellar Expert
Engine Account	`GBUQJORY2GBXU2Z3...`	Stellar Expert

📸 Screenshots

Click to view all screenshots

1. Onboarding Screen

A seamless Web3 onboarding experience — connect your Freighter wallet to get started.

2. Main Dashboard

Track your total automated wealth, active rules, and recent on-chain activity.

3. AI Financial Coach

Chat with the AI to build complex savings rules in plain English.

4. Chat Interface

Conversational automation rule creation powered by Groq and Qwen3.

5. Automation Rules

View, pause, and manage all your active financial automation triggers.

6. Goal Tracking

Set financial milestones and link them to rules for automatic progress tracking.

7. On-Chain Vaults

Funds are autonomously routed to your vaults when rules execute.

8. Account Settings

Set daily/weekly spending limits and manage your automation settings.

9. Mobile View

Fully responsive — works seamlessly on mobile.

10. Mobile Dashboard

All your data accessible in a clean, single-column mobile layout.

🚀 Quick Start

Prerequisites

Tool	Version
Node.js	>= 18
npm	>= 9
Rust	stable
Freighter Wallet	Browser extension (Testnet mode)

1. Clone

git clone https://github.com/thisisouvik/autopilot.git
cd autopilot

2. Backend

cd backend
npm install
cp .env.example .env   # Fill in your values
npm run dev            # Starts on http://localhost:3001

Required backend environment variables

DATABASE_URL=postgresql://user:pass@localhost:5432/autopilot
JWT_SECRET=a-very-long-random-string
VAULT_ENCRYPTION_KEY=<64-char hex — see below>
GROQ_API_KEY=your-groq-api-key
AUTOPILOT_PUBLIC_KEY=your-stellar-testnet-engine-public-key
AUTOPILOT_SECRET_KEY=your-stellar-testnet-engine-secret-key
STELLAR_NETWORK=testnet
REDIS_URL=redis://localhost:6379

Generate encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Fund your testnet engine account for free:

npm run friendbot

3. Frontend

cd frontend
npm install
cp .env.example .env.local   # Fill in your values
npm run dev                   # Starts on http://localhost:3000

Required frontend environment variables

NEXT_PUBLIC_API_URL=http://localhost:3001/api
NEXT_PUBLIC_STELLAR_NETWORK=testnet

4. Soroban Contract (optional)

cd contracts
cargo test           # Run unit tests
stellar contract build   # Build to WASM

See CONTRIBUTING.md for full contract deploy instructions.

📂 File Structure

autopilot/
├── .github/
│   ├── workflows/          # CI, security audit
│   ├── ISSUE_TEMPLATE/     # Bug report, feature request, contract bug
│   ├── CODEOWNERS          # Auto-review assignments
│   ├── dependabot.yml      # Automated dependency updates
│   └── pull_request_template.md
├── backend/
│   └── src/
│       ├── engine/         # Horizon stream, rule processor, BullMQ queue
│       ├── stellar/        # Transaction builder, vault manager, keypair utils
│       ├── routes/         # REST API endpoints
│       ├── lib/            # DB client, engine helpers
│       ├── middleware/      # JWT auth
│       └── migrations/     # PostgreSQL schema
├── contracts/              # AutopilotVault (Soroban / Rust)
│   └── src/
│       ├── lib.rs          # Contract implementation
│       └── test.rs         # Contract unit tests
├── frontend/
│   └── src/
│       ├── app/            # Next.js App Router pages
│       └── components/     # Reusable UI components
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE

🧪 Testing

Backend E2E Tests

cd backend
npx tsx src/scripts/e2e.ts

The E2E suite simulates a full user lifecycle:

Creates a mock user in PostgreSQL
Creates a rule and a goal
Calls Groq API to verify AI parsing
Creates and funds a real Vault on Stellar Testnet
Verifies DB state and cleans up mock data

Soroban Contract Tests

cd contracts
cargo test

🛑 Error Handling

Scenario	How AutoPilot Handles It
AI Misunderstanding	Schema validation catches bad AI output; user is prompted to rephrase
Duplicate Payment Event	`txHash` deduplication check before processing (see #8 for DB-level fix)
Horizon Stream Disconnect	Fallback to BullMQ queue; reconnect logic tracked in #11
Insufficient Engine Funds	API returns a clear 500 with a descriptive message
Stellar Tx Timeout	30-second timeout + catch block prevents retry loops
Spending Limit Hit	Rule is blocked gracefully; result logged as `blocked`

🗺️ Roadmap

Status	Feature
✅ Done	AI rule creation via natural language
✅ Done	XLM automated savings/investment vaults
✅ Done	Soroban smart contract deployment (testnet)
✅ Done	Goal tracking with linked rules
✅ Done	Daily/weekly spending limits
🔄 In Progress	USDC payment event support (#9)
🔄 In Progress	Horizon stream reconnection logic (#11)
📋 Planned	Multi-sig vault security
📋 Planned	On-chain engine authorization via Soroban (#5)
📋 Planned	Mobile app (React Native)
📋 Planned	Mainnet deployment (post security audit)

🤝 Contributing

We welcome all contributions — bug fixes, features, documentation, and Soroban contract improvements!

Read the Contributing Guide
Check open issues — especially ones tagged good first issue
Fork → branch → PR

Please follow our Code of Conduct.

🔐 Security

AutoPilot handles Stellar keypairs and user funds. If you find a security vulnerability, please do not open a public issue. Instead, use GitHub Security Advisories.

See SECURITY.md for the full responsible disclosure policy.

📝 License

This project is licensed under the MIT License — see LICENSE for details.

👥 Contributors

Thanks to everyone who has contributed to AutoPilot! 🌟

_{Contributor avatars powered by contrib.rocks}

If you find AutoPilot useful, please consider giving it a ⭐ — it helps others discover the project!

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
backend		backend
contracts		contracts
frontend		frontend
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
contract.yml		contract.yml

Latest commit

History

Folders and files

Repository files navigation