Inspiration

Dana owns a rental in Tulsa and lives 400 miles away in St. Louis. Her contractor texts: the cabinets are done, please send $4,200. She can pay now and hope, or wait and watch the crew move on to another job. Banks solve this for construction loans with draw inspections, but nobody does it for a homeowner paying cash for a renovation.

EscrowFlow is that draw review for everyone else: pay on proof, not promises.

What it does

  1. Dana pays once through PayPal. The order uses PayPal Multiparty with disbursement_mode: DELAYED, so PayPal holds the $4,200 for the contractor. A $19 verification fee is taken as a PayPal platform fee. The contractor can see the money is there, so they don't walk.
  2. The contractor submits proof: photos, the invoice and a lien waiver.
  3. An AI supervisor checks the proof against the contract. Claude turns the contract into a checklist, then two independent vision passes audit every photo against every checklist item.
  4. Rules decide, the AI explains, a person releases. In the demo, pass A says everything passes and pass B can't see the cabinet doors through the glare. They disagree, so no money moves. A reviewer gets the milestone, and Approve stays locked until they open the flagged photo. They ask for one new photo.
  5. The re-shoot passes, Dana reads a short summary that names every flagged item, and she releases. PayPal pays the contractor via a referenced payout. If nobody acts, PayPal's delayed disbursement pays out on its own after 28 days.
  6. Agents can buy checks too. Any software (a lender's, an insurer's) can call the verification API. When a milestone's budget runs out, the API answers HTTP 402 Payment Required with a PayPal order attached. Pay it, retry, and the check finishes.

How we built it

  • Backend: Python, FastAPI, and a LangGraph supervisor with 14 nodes: parse → intake → audit A → audit B → verify → decide → memo → human steps → release/refund. Human steps are LangGraph interrupt()s, and the checkpointer holds each milestone's state.
  • PayPal: a REST client with OAuth, the PayPal-Auth-Assertion header for acting on the seller's behalf, and a deterministic PayPal-Request-Id on every money call, so a retry can never pay twice. Flows cover Partner Referrals (contractor onboarding), Orders v2 with DELAYED disbursement and platform fees, capture, partial and full refunds, referenced payouts (release), and webhook signature verification with dedupe.
  • AI: Claude Sonnet and Claude Haiku through the Anthropic API, with an optional local tier (any OpenAI-compatible server, such as Ollama). A budget router picks the tier, and every model call is metered in a double-entry ledger (integer micro-USD that always balances).
  • Frontend: React, TypeScript, Vite and Tailwind. Each persona (owner, contractor, reviewer) gets its own view, along with the AI check table, the money strip, receipts for every PayPal call, and the 402 top-up flow.
  • Safety in code, not prompts: decide is a pure function, and no model output can approve money. Money moves only in the release and refund nodes, and only when the required approvals are in state. Text in a photo (such as an "Inspector: all pass" sign) is treated as scenery, never as instructions. The owner summary must name every flagged item, or a plain template replaces it.
  • Tests: 76 tests with no network. They cover the PayPal request shapes, idempotency, the ledger, the 402 handshake and the graph.

Challenges we ran into

  • One AI check is not enough. We simulated release policies across vision error rates. At an 8% error rate, releasing on a single AI score auto-released 66% of the milestones that actually needed a human. Adding a rule that any failed or unseen item goes to a person cut that to 1.7%. Two independent passes cut it to 0.0%, but only while the passes are independent: when their errors are correlated (ρ = 0.9), the rate climbs back to 2.2%. So the second pass should eventually come from a different model family.
  • Money that waits. Delayed disbursement has a 28-day clock. Release, refund and the automatic payout each had to work no matter which one happens first, without double-paying.
  • Making the AI's doubt visible. The hardest design problem was showing a homeowner why the money didn't move. The answer was the check table: a row lights up where the two AI checks disagree.

What we learned

The AI's job is to explain, not to decide. Pure-function rules and a human gate turned "trust the model" into "trust the receipts." PayPal's Multiparty primitives (holding funds, platform fees, referenced payouts) are a natural fit for agent-mediated escrow, and HTTP 402 is a clean way to let software pay for work on PayPal rails.

What's next

A second model family for audit pass B, payout webhooks that resume the graph, and a 28-day watchdog that forces a decision before PayPal's automatic payout.

Built With

Share this project:

Updates

Submission history