PactPal

Inspiration

Freelancing is broken. We've all seen it — a friend does weeks of work and never gets paid, or a client pays upfront and gets nothing delivered. The existing platforms either charge huge commissions, offer no real dispute resolution, or just tell you to "work it out." We wanted to build something that actually protects both sides, without needing a lawyer or a 20% platform cut.

That frustration is what gave birth to PactPal — a zero-trust escrow platform where funds are frozen, work is verified by an AI Referee, and nobody can ghost without consequences.

What it does

PactPal lets a hirer and a freelancer sign a smart digital contract together. Here's the flow:

Hirer creates a contract with a priced checklist of deliverables
Freelancer reviews, negotiates, and dual-signs the terms
Funds are frozen via a PayPal authorization hold (not captured — just reserved) so the buyer can't walk away
Freelancer submits work mapped to checklist items — text, images, links, or files
AI Referee (powered by multimodal LLM analysis) reviews each submission against the agreed checklist
Settlement happens automatically — full release, partial capture, or void — with on-chain-style SHA-256 receipts as proof

No middleman. No manual arbitration delays. No ghosting.

How we built it

Frontend: Next.js 14 (App Router) with Tailwind CSS — server and client components split carefully for performance
Backend: FastAPI (Python) handling AI Referee logic, contract state machine, and webhook orchestration
Database: Supabase (PostgreSQL) with row-level security enforcing buyer/seller/admin role isolation
Payments: PayPal Orders API with intent: AUTHORIZE — funds are placed on a 29-day authorization hold, captured only when the Referee confirms delivery
AI Referee: Multimodal Gemini API — parses submission evidence (images, text, links) and cross-references against contract checklist items to generate a structured verdict
Auth: Google OAuth with role selection (buyer/seller) on first login, session handled via Supabase Auth

The contract follows a 10-state finite state machine — from DRAFT → SIGNED → FUNDED → IN_PROGRESS → SUBMITTED → VERIFIED/DISPUTED → SETTLED — with every transition gated by role-based checks.

Challenges we ran into

Honestly, a lot. The hardest part was making the PayPal authorization + capture flow bulletproof. PayPal's sandbox behaves differently from their docs in several edge cases — partial captures, voiding residuals, and reauthorization after the honor period all needed custom handling.

Getting the AI Referee to give consistent, structured verdicts was another challenge. Raw LLM output isn't reliable for financial decisions, so we had to engineer a strict prompt schema and parse the output into a typed verdict object before any payment action triggers.

We also had to manage concurrent state transitions carefully — two parties acting on the same contract simultaneously can cause race conditions. We solved this with idempotency keys and backend-gated transitions.

And of course — building all of this in a hackathon window while keeping the UI clean and the demo stable was its own kind of sport.

What we learned

PayPal's authorize-and-capture model is powerful but fragile at the edges — real production use needs reauthorization jobs running every ~3 days
Designing a finite state machine upfront saves enormous debugging time later
Multimodal AI works remarkably well for submission verification when you give it structured context
Supabase's RLS is genuinely great for enforcing access control at the DB layer — not just the API layer

What's next for PactPal

On-chain receipts using a lightweight smart contract for tamper-proof settlement records
Reauthorization scheduler to keep escrow holds alive beyond the 29-day PayPal limit
Dispute escalation to human arbitrators when the AI Referee flags ambiguous cases
Mobile app so freelancers can manage contracts and submissions on the go
Expanding beyond PayPal to support Stripe, UPI, and crypto payment rails