Split Pay

Split bills instantly with friends — sponsored network fees on Celo (no extra fee for payers when relayer is enabled).

A modern Celo blockchain application built with Next.js, TypeScript, and Turborepo, featuring a fully-compliant ERC-8004 AI Agent.

🌐 Live Preview

✨ Features

• Sponsored payments: Relayer covers network fees via relayPayWithPermit (browser wallets) and relayPayWithAllowance (MiniPay — no off-chain signing) on Celo Mainnet.
• Multi-Token Support: Supports USDC, USDm, and USDT payments, automatically prioritised in the UI (USDC → USDm → USDT).
• Flexible Off-chain Setup: Bill creation does not require participant addresses upfront; they are dynamically captured during the payment flow.
• Itemized Splitting: Supports custom participant items, quantities, and individual amounts.
• ERC-8004 AI Agent:
  • Exposes metadata profile at /agent.json and /api/agent/profile.
  • Implements 5 key capabilities: registering bills, checking unpaid members, querying transaction summary, calculating settlement plans, and querying bill statuses.
  • Features natural language intent routing via server-side Gemini classifier.
  • Displays interactive, real-time widgets in the AI chat page (/ai).

🔄 Workflow Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                       CORE SPLIT-PAY FLOW                           │
│                                                                     │
│  [ Initiator ] ──(1. Create Bill Group)──▶ [ Split-Pay App ]        │
│                                                   │                 │
│                                         (2. Gen Payment Links)      │
│                                                   │                 │
│                                                   ▼                 │
│                                          [ Share Link (WA/TG) ]     │
│                                                   │                 │
│                                                   ▼                 │
│   [ Show Top-up CTA ] ◀──(Insufficient)─── [ Member opens link ]    │
│                                                   │                 │
│                                              (Sufficient)           │
│                                                   │                 │
│                                                   ▼                 │
│  [ Update Status: Paid ] ◀─(5. BillPaid)─ [ SplitLedger Contract ]  │
│            │                                      ▲                 │
│            │                                      │                 │
│     (6. All Paid)                      (4. Gasless Transaction)     │
│            │                                      │                 │
│            ▼                                      │                 │
│    [ Group Completed ] ───────────────────────────┘                 │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                      ERC-8004 AI AGENT FLOW                         │
│                                                                     │
│  [ User ] ──(1. Natural Language Chat)──▶ [ AI Assistant UI ]       │
│     ▲                                             │                 │
│     │                                      (2. API Request)         │
│     │                                             │                 │
│     ▼                                             ▼                 │
│  [ Interactive Widget ] ◀──(5. Response)── [ Next.js API Backend ]  │
│                                                   │                 │
│                                            (3. Call Gemini)         │
│                                                   │                 │
│                                                   ▼                 │
│                                          [ Gemini Classifier ]      │
└─────────────────────────────────────────────────────────────────────┘

🚀 Quick Start

The easiest way to get started is by running the setup script:

./setup.sh

This script will:

• Check for prerequisites (Node.js, pnpm, Foundry)
• Setup smart contract dependencies and remappings
• Run contract tests
• Configure initial environment variables
• Install all project dependencies

🛠️ Getting Started (Manual)

If you prefer manual setup:

1. Install dependencies:

   pnpm install

2. Configure environment: Create apps/web/.env.local based on the template:

   NEXT_PUBLIC_WC_PROJECT_ID=your_wc_project_id
   CELO_RPC_URL=https://forno.celo.org
   NEXT_PUBLIC_GASLESS_PAY_ENABLED=true
   RELAYER_PRIVATE_KEY=your_relayer_private_key
   
   # ERC-8004 AI Agent Configuration
   NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key
   NEXT_PUBLIC_BASE_URL=https://split-pay-minipay.netlify.app
   AGENT_CHAIN_ID=42220

3. Register the AI Agent (on-chain registry): To bind the agent wallet address with the metadata profile on Celo Mainnet:

   pnpm --filter web register-agent

4. Start the development server:

   pnpm dev

5. Open http://localhost:3000 in your browser.

🔗 Deployed Contracts

• SplitLedger (Celo Mainnet): 0x6b08ae6a942ed2fbb9b3885049430ad58c515fa6
• ERC-8004 AI Agent Registry (Celo Mainnet): 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ERC-8004 Registered Agent: AI Agent Card #9100 on 8004scan (Wallet: 0x6599d6E7af6b13A2fCa80C7CA2035a94eE913293)

📂 Project Structure

This is a monorepo managed by Turborepo:

• apps/web: Next.js 16 application with React 19.
• apps/contracts: Foundry-based smart contracts (Solidity).

📜 Available Scripts

• pnpm dev: Start development servers for all apps.
• pnpm build: Build all packages and apps.
• pnpm lint: Lint all packages and apps.
• pnpm type-check: Run TypeScript type checking.
• pnpm --filter web register-agent: Register the AI agent on Celo Mainnet.

🧱 Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• UI/UX: React 19, Tailwind CSS, shadcn/ui
• Blockchain: Celo, Wagmi, Viem, RainbowKit
• Contracts: Foundry
• Monorepo: Turborepo
• Package Manager: PNPM