Vouch: AI escrow for freelance work

Milestone escrow on PayPal, run by AI agents: they draft the contract, verify the delivered work, and release payment or split disputes. Marketplace trust without the 20% fee.

Comment

Try it

A 3-minute walkthrough for judges:

  1. Click Load demo contract.
  2. As the client, fund Milestone 1 with the PayPal button. Log in with the sandbox buyer account: [email protected] / U)39&Tpb
  3. Click View as freelancer, paste https://vouch-crnw.onrender.com/demo/bakery.html as the deliverable, and click Submit for AI review. The Verifier checks every criterion against the live page, and the Settlement Agent releases the payout through PayPal Payouts.
  4. To see a dispute, fund Milestone 2, submit weak work, click Open dispute as the client, then Request binding AI ruling to watch the Mediator rule a payout, refund or split, depending on the evidence.
  5. Open Ledger to see every PayPal capture, payout and refund ID.

The demo runs on a free Render instance. If it has been idle, the first page load can take up to a minute.

Inspiration

Anyone who has freelanced or hired a freelancer knows the standoff. The freelancer doesn't want to start until they're paid. The client doesn't want to pay until they've seen the work. Online, between strangers in different countries, nobody has a good answer.

Today you get one of two bad options. You can trust a stranger: buyer protection on consumer payment platforms generally doesn't cover services, so a client who pays up front has little recourse, and a freelancer who delivers first can be ghosted. Or you can join a marketplace that takes 10–20% of every job, locks both of you into its platform, and settles disputes with a human reviewer skimming a long message thread.

We asked a simple question: what if the neutral third party was an AI agent that reads the contract, actually looks at the work, and moves the money through PayPal?

What it does

Vouch is milestone escrow run by AI agents on PayPal.

  1. The client describes the job in plain English. The Contract Architect agent turns the brief into 1–5 milestones. Each milestone gets a price (all prices add up to the budget) and objectively verifiable acceptance criteria, such as "site is live at a public URL and renders on a 375px phone screen" rather than "looks professional." The agent also flags ambiguities the client should clarify before paying.
  2. The client funds each milestone with PayPal Checkout. The payment is captured and held in escrow. The freelancer can see the money is there before they start.
  3. The freelancer submits the work: a live URL, a GitHub repo, notes, or a screenshot.
  4. The Delivery Verifier agent checks the evidence itself. It fetches the live page, reads the repo's README and file tree through the GitHub API, and looks at uploaded screenshots. It scores every criterion as met or not met, cites what it found, and gives the freelancer concrete fixes for anything missing.
  5. The Settlement Agent moves the money. If the work passes with high confidence and the client turned on auto-release, the agent cross-checks the escrow order with PayPal (using the PayPal Agent Toolkit) and pays the freelancer through PayPal Payouts. Nothing counts as paid until PayPal says so: a signature-verified PayPal webhook moves the payout from "Settling with PayPal" to "Confirmed by PayPal" live on the page. If the work fails, the milestone goes back for revision.
  6. Disputes get a binding AI ruling. Either side can open a dispute and both submit statements. The Mediator agent weighs them against the contract and the verifier's evidence and rules on a split, for example "the freelancer earned 70%." The Settlement Agent then carries out the ruling as a partial Payout plus a partial Refund.

Every action, whether from a person, an AI agent or PayPal, goes into an escrow dashboard built with AG Grid and AG Charts: where the money is, escrow by contract (click a bar to filter the ledger), the escrow balance over time, and an audit grid with PayPal capture, payout and refund IDs, live PayPal status, a totals row and CSV export.

How we built it

  • Next.js 16 + React 19 + Tailwind for the app, using server actions for the escrow workflow.
  • PayPal:
    • JavaScript SDK Smart Buttons for funding
    • Orders v2 (create + capture) to put funds in escrow
    • Payouts API to release funds to the freelancer
    • Payments v2 capture refunds (full and partial) to return funds to the client
    • The PayPal Agent Toolkit (get_order, get_refund) as the Settlement Agent's read tools, so it confirms the escrow state with PayPal before moving money
    • Webhooks (PAYMENT.PAYOUTS-ITEM.*, PAYMENT.CAPTURE.REFUNDED), checked with PayPal's verify-webhook-signature API and applied once per event, with polling as a fallback, so every payout and refund is confirmed settled
  • AI: four agents built on the Vercel AI SDK v7 with Claude (OpenAI works as a drop-in alternative). We used structured outputs (zod schemas) for contracts, verdicts and rulings, multi-step tool calling for the Verifier and Settlement agents, and image input for screenshots.
  • AG Grid + AG Charts for the escrow dashboard: three linked charts, plus a grid with filters, quick search, color-coded money flows, a live PayPal status column, a pinned totals row for the filtered rows, and CSV export.
  • SQLite via Node's built-in node:sqlite, so judges can clone and run the app with no database to set up.
  • Render blueprint (render.yaml) for one-click deployment.

Challenges we ran into

  • Letting an AI agent move money safely. This was the core design problem. Our rule is the AI decides, the code enforces:
    • Each agent run is bound to a single milestone in code, so the model can't choose which escrow to touch.
    • One escrow module checks released + refunded ≤ funded on every money movement, whether a human or the agent triggered it.
    • Every Payout and Refund carries a deterministic PayPal-Request-Id, so a retried call can never pay twice.
  • Mixing SDK versions. The PayPal Agent Toolkit is built for AI SDK v4, and we wanted the current v7 features (structured output alongside tool calls). We wrote a small adapter that re-wraps each toolkit tool with the v7 tool() helper, keeping the toolkit's own schemas and executors. One toolkit schema produced JSON Schema that strict tool calling rejects, so we exposed only the read tools the agent actually needs.
  • Making verification trustworthy. A verifier that believes "trust me, it's done" is useless. We gave it a tool to gather evidence itself and told it that anything it can't verify counts as not met. For GitHub links it pulls the README and file tree through the API instead of scraping HTML, which gives far better evidence.
  • Writing criteria an AI can verify. Vague criteria make verification impossible. Most of our prompt work went into getting the Contract Architect to write testable criteria and to flag ambiguities instead of inventing requirements.
  • Knowing when money has actually moved. A payout returns PENDING; PayPal settles it later. We track every payout and refund until PayPal confirms it, through signature-verified webhooks (deduplicated, since PayPal retries) with polling as a fallback when webhooks can't reach the app.
  • Fetching untrusted URLs safely. The verifier fetches links chosen by the freelancer from our server, so in production it refuses anything that resolves to a private, loopback or link-local address (such as cloud metadata), checking every redirect hop.
  • Keeping the wait bearable. Verification can take 20–60 seconds while the agent inspects sources, so the UI shows a live progress panel describing what the agent is doing.

Accomplishments that we're proud of

  • A complete escrow lifecycle on PayPal: fund → verify → pay out, refund, or split. It's a working product flow, not a chatbot attached to an API.
  • Partial settlements: an AI ruling becomes a real partial Payout plus a partial Refund in one step. This is the part of escrow that is slowest and most expensive for people to do by hand.
  • Guardrails that make autonomous payments reasonable to allow: escrow scoping, money limits, idempotency, a confidence threshold for auto-release, and a full audit trail.
  • A verifier that shows its evidence. Every verdict lists what was checked and what was found, so both parties can see why.

What we learned

  • Agentic payments are mostly a trust-design problem, not a model problem. The model's judgment is valuable, but code has to enforce the limits around it.
  • The best use of AI here isn't the chat interface. It's the structure around the deal: turning an informal brief into checkable criteria makes everything later (verification, dispute resolution) cheap and fair.
  • PayPal's building blocks (Orders, Payouts, Refunds, and the Agent Toolkit) are enough to build a real escrow flow without a payments backend of our own.

What's next for Vouch: AI escrow for freelance work

  • PayPal Multiparty with delayed disbursement: freelancers onboard as sellers and each milestone's funds stay with PayPal until the agents release them, so Vouch never takes custody of the money. This is the production path; the prototype holds sandbox funds in the platform's business account.
  • Vaulted payment methods, so a client can approve a whole multi-milestone contract once.
  • Verifier plugins for Figma files, app builds, and running the freelancer's test suite in a sandbox.
  • A human appeal path for high-value disputes, with the AI's evidence report as the starting point.
  • Reputation from verified history: a track record of AI-verified milestones a freelancer can bring to any client.

Built With

Share this project:

Updates

Submission history