Inspiration
A lot of paid work is agreed in a chat: a freelance designer and a bakery owner on WhatsApp, a handyman found in a neighborhood group, a video editor hired over Instagram DMs. The "contract" is a few messages, and when it goes wrong, someone loses money. Either the freelancer delivers and gets ghosted, or the client pays upfront and gets half the work. Marketplaces only protect deals made inside them and take a big cut. Traditional escrow is built for houses, not a $400 logo. I wanted to protect the deals people are already making, right where they make them.
What it does
Handshake turns any chat into a protected deal.
- Paste the conversation (text or screenshots). The AI Agreement Drafter turns it into milestones, amounts, due dates and testable acceptance criteria. It also flags the gaps that usually cause fights, like no revision limit, vague scope or no IP terms, and adds a fix as a term in one click.
- Both parties sign from private links. The other person needs no account.
- The client funds each milestone with PayPal (Orders v2 checkout, or a PayPal invoice). The money is held in escrow, so the freelancer knows it's really there before starting.
- The freelancer delivers files, photos or links. The AI Delivery Verifier checks every acceptance criterion against the evidence (it inspects images with vision and reads linked pages) and gives the client a per-criterion report.
- Release: the client approves and PayPal Payouts sends the money. If the check passes and the client goes silent, funds auto-release after 72 hours, so freelancers can't be ghosted.
- Disputes: either side freezes the funds and gives their side. The AI Mediator weighs the agreement, the verification report and both statements, then proposes a split with reasoning tied to the terms. When both accept, Handshake executes it automatically: a PayPal payout for the freelancer's share and a partial PayPal refund to the client.
Design rule: AI advises, people decide, PayPal moves the money. The AI never moves funds on its own. Every action is recorded in a per-deal ledger with the real PayPal order, capture, refund and payout IDs.
How we built it
- Backend: Node.js + Express in TypeScript, with SQLite through Node's built-in
node:sqlite, so there are no native dependencies. A deal engine owns the milestone state machine (AWAITING_FUNDING → FUNDED → SUBMITTED → RELEASED, orDISPUTED → SETTLED, orREFUNDED) and is the only code allowed to move money. - PayPal: Orders v2 with redirect approval (create → approve → capture), Payments v2 for full and partial refunds, Payouts v1 for releases (with payout status polling until PayPal confirms SUCCESS), Invoicing v2 as an alternative way to fund, and signature-verified webhooks. Every money-moving call sends a
PayPal-Request-Idfor idempotency, and a per-milestone lock prevents double payouts. - AI: Google Gemini (3.x Flash family) with JSON-schema structured output for all three agents. The Verifier is multimodal: it gets the uploaded images and the text of linked pages. Prompts treat evidence and statements strictly as data, as a guard against prompt injection.
- Frontend: React + Vite + Tailwind. A clear escrow summary, milestone cards that change by role and state, live AI reports, and an activity ledger.
- Testing: a Playwright end-to-end test drives the whole flow through the real PayPal sandbox checkout: draft, sign, pay, deliver, verify, dispute, mediate, settle. I used the same scripts to record the demo video.
Challenges we ran into
- Payouts region restriction: my first sandbox business account was in a country that can't send Payouts, so I rebuilt the sandbox setup with US accounts. I also added a clearly labelled fallback, so anyone can still run the project.
- Free-tier AI limits: Gemini's free tier allows about 20 requests per model per day and often returns "model overloaded" errors. I built model rotation with per-model cooldowns and timeouts, so the app quietly switches to another model instead of hanging.
- Making AI output trustworthy for money decisions: acceptance criteria had to be objectively checkable, and the mediator had to cite the agreement rather than "vibe". Strict schemas and careful prompts made the outputs consistent enough to act on.
- Automating the PayPal sandbox checkout for a repeatable end-to-end test and demo recording.
Accomplishments that we're proud of
- A complete, working loop with real sandbox money: escrow capture, payout to the freelancer, and an AI-mediated split settled as a payout plus a partial refund, all with real PayPal transaction IDs.
- The AI does useful work at three points in the deal, not just as a chatbot attached at the end.
- Protection in both directions: clients only pay for work that meets the agreement, and freelancers can't be stalled forever.
- A product that stays demoable: if the PayPal sandbox keys stop working, it automatically switches to a clearly labelled simulation mode.
What we learned
- How PayPal's Orders, Payments, Payouts, Invoicing and webhooks fit together into a real escrow flow, and why idempotency keys matter when money moves.
- Structured output is what makes LLMs safe to wire into money flows. Free text isn't good enough.
- Keeping humans in control of the final decision is what makes an AI referee acceptable to both sides.
What's next for Handshake: Turn Any Chat into a Protected Deal
- Move from the platform-held sandbox model to PayPal's multiparty marketplace capabilities: seller onboarding, delayed disbursement and platform fees.
- PayPal Disputes API integration: automatically submit the agreement, verification report and ledger as evidence.
- A WhatsApp/Telegram bot so a deal can be created without leaving the chat.
- Multi-currency deals for cross-border freelancers, and a human appeals tier above the AI Mediator.
- Reputation built from completed Handshakes.
Built With
- express.js
- gemini-api
- google-gemini
- node.js
- paypal
- paypal-orders-api
- paypal-payouts
- paypal-sandbox
- paypal-webhooks
- playwright
- react
- sqlite
- tailwindcss
- typescript
- vite