Inspiration

The money side of a small remodel GC's business still runs on spreadsheets, email and bank transfers. Every month each trade sends a pay app ("rough-in is 100% done, pay us $X"). The GC has to check each line against the schedule of values (SOV), catch overbilling and billing for excluded scope, hold back retainage, confirm the license is still active, collect a lien waiver, and then actually pay. Overbilling slips through, retainage is tracked by hand, and the homeowner's draw is invoiced somewhere else.

Procore Pay, GCPay and Textura cover this for big commercial GCs. The owner-run remodeler doing a few kitchens and additions a year gets nothing. PayPal already gives that GC authorization holds, payouts and invoices, so the missing piece is the check before the money moves. That check is the part AI can help with, as long as it isn't the AI setting the amount.

What it does

TradePulse Pay runs the money side of a residential job for three roles: GC, subcontractor and homeowner.

  1. Execute the subcontract. Code generates the SOV and milestones from the awarded bid. Excluded scope stays out of the contract sum.
  2. Fund a milestone. The GC approves a PayPal Orders v2 AUTHORIZE order. The money is held, not captured. An hourly job reauthorizes after the 3-day honor period and marks expired funding.
  3. The sub files a pay app with % complete per line.
  4. Review. A deterministic rules engine returns per-line verdicts: ok, overbilled, excluded scope, front-loaded or out of sequence. Code computes every recommended dollar from the SOV and the funded tranches. Mistral Large writes the per-line explanation from that structured evidence. It cannot author or change an amount. A KERNEL hosted browser checks the sub's California license on the CSLB site, with a visible live view and a 24-hour cache.
  5. The pay agent proposes, the GC decides. An AI SDK agent with read-only PayPal Agent Toolkit tools (list_invoices, get_invoice, get_order, list_transactions) can only insert proposals (capture, payout, hold). Money moves only after the GC approves, trims a line with a recorded reason, or rejects. Then PayPal partially captures from the authorization and pays the sub net of retainage through Payouts, and the retainage ledger is credited.
  6. Owner billing. Draws and change orders go to the homeowner as PayPal Invoicing v2 invoices. Retainage is released at closeout as a single payout of the ledger balance, behind an optional lien-waiver gate.
  7. One set of numbers. A five-cell money strip shows collected from homeowner, paid to subs, retainage you hold, retainage held from you and owed this week. Every number links to its receipts.

The settled reference job (real sandbox money): Lopez Kitchen Remodel, an $86,500 contract.

  • Ortiz Plumbing claimed $5,400. The conservative rules review suggested $2,000 and cut the $1,400 "Fixtures set" line to $0, because that milestone wasn't funded.
  • The GC kept the cut, overrode Rough-in with a recorded reason, and approved $4,000.
  • 5% retainage held $200. PayPal paid $3,800 net (payout batch D5V7XEN5YZH4C).
  • Homeowner Draw #1 was paid by PayPal invoice: $3,600 after 10% owner retainage (INV2-5ZNS-USY8-KBFD-L3B9).
  • A $1,200 change order was invoiced and paid (INV2-RCJ4-Z8GD-4A33-TDJC).

The guided-run reference (commercial-style stress test, also settled): A401-DEMO-PAY-20261101-02, a $55,000 subcontract.

  • An intentionally overbilled $13,500 claim from a labeled billing agent got a rules recommendation of $320: overbilled ×2, excluded scope ×1, out of sequence ×1, with Mistral explaining each line.
  • The GC cut it further to $288. PayPal captured that amount and paid $259.20 net, with $28.80 retainage held.
  • A separate honest $2,000 claim was paid $1,800 net.
  • A $1,850 change-order invoice was paid by the Owner, and the $228.80 retainage balance was released by payout.
  • These are real sandbox receipts for partial progress, not full payment of the subcontract. Real Mistral reviews, two COMPLETED captures, two SUCCESS payouts, a PAID Owner invoice and a SUCCESS retainage release were independently checked on Nov 1.

Lien-waiver gate: this is an opt-in release control, not a form. When an agreement enables it, a payout waits until the sub signs a conditional waiver for that payment. A retainage release needs a separate signed waiver for exactly the amount released. Each signature records the SHA-256 of the statement text, a timestamp, the forwarded-address header when one is present (or says none was available), and the signer's browser string.

How it differs

Procore Pay, GCPay, Oracle Textura and Siteline automate the pay-app workflow for larger commercial GCs. TradePulse Pay's review is contract-scope-aware: it flags excluded scope and out-of-sequence or unfunded-milestone billing against the awarded SOV, not only arithmetic. A small GC without a Textura or GCPay contract can pay an approved sub through PayPal Payouts the same day instead of waiting for a check run.

Potential impact

On US commercial jobs, a trade partner waits about 50 days from pay-app submission to payment. That's the median in Built's 2026 transaction data; Billd's 2026 National Subcontractor Market Report survey says an average of 51 days. On top of that, retainage (typically 5–10% of each progress payment) is held until closeout. Most of that wait is the review step and the paperwork, not the money transfer. TradePulse Pay shortens the review, pays through PayPal once the GC approves, and keeps retainage on the same ledger, so the GC, sub and homeowner all read one payment history. Residential remodelers feel this most, because they have the least back-office support.

How I built it

  • Frontend: React 18, TypeScript, Vite and Tailwind, hash-routed and served from Cloudflare Pages.
  • Backend: Convex for the database, queries, mutations and actions, the HTTP router (/paypal/webhook, /api/health, /llms.txt), crons (the honor-period watcher), file storage and Convex Auth (email and password with gc, sub and owner roles).
  • PayPal:
    • @paypal/paypal-server-sdk for Orders and Payments (authorize, partial capture, void, reauthorize).
    • Plain REST for Payouts, Invoicing v2 and webhook signature verification.
    • @paypal/react-paypal-js for funding buttons and @paypal/agent-toolkit for the agent's read-only tools.
    • Every PayPal write sends a PayPal-Request-Id and writes an audit row without secrets. A duplicate webhook event id is a no-op.
  • AI: the Vercel AI SDK v7 with @ai-sdk/mistral (Mistral Large) for structured review explanations and bounded tool calls. Anthropic is an optional alternative provider. If no provider is available, the review is labeled "Offline rules engine" and is never presented as AI.
  • Money: integer cents everywhere. convex/lib/money.ts is the only place an amount becomes a PayPal string.
  • Safety: every public Convex function is role- and tenant-guarded, and npm run verify:guards checks 269 public functions. A sub sees only its own agreements. The homeowner can pay invoices but can't approve or fund.
  • Other tools: KERNEL (@onkernel/sdk) for the CSLB lookup. APIMatic Context Plugin during development of the Server SDK code (logged in docs/apimatic-log.md). A Postman v2.1 collection for every endpoint and PayPal call. AgentMail for verification codes and procurement inboxes. Firecrawl for subcontractor discovery.
  • Tests: 200+ Vitest files and 2,300+ tests (unit, convex-test integration, role guards and money), plus a docs link check, a guard audit and CI on every push.

What changed since Oct 1 (existing-project disclosure)

TradePulse Pay is built on TradePulse Pro, my September 2026 procurement app, which I submitted to the Convex hackathon. TradePulse Pro covers CSI scoping, Firecrawl subcontractor discovery, AgentMail RFQ inboxes, bid leveling and A401-style subcontract drafts. Its last commit is 2ad5543 (Sep 22). None of the payment side existed before this hackathon.

Everything PayPal and payments is new in the submission period. The first PayPal commit is c7986da on Oct 7, and there are 204 commits on main since Oct 1 (git log 2ad5543..main):

  • Auth and roles: Convex Auth with gc, sub and owner roles. Role guards on every public function, old and new.
  • Payments: integer-cents schema, a PayPal client with token cache, idempotency, backoff and audit logs, SOV and milestones on execution, AUTHORIZE funding, partial capture, void, reauthorize, Payouts net of retainage, the retainage ledger and closeout release, Invoicing v2 change orders and draws, a signature-verified webhook, the hourly honor-period watcher, payout retry and ledger reconciliation.
  • Pay apps and AI: sub pay-app submit and withdraw, the rules review with Mistral explanations and a labeled offline fallback, KERNEL CSLB checks, and pay-agent proposals with a GC approval inbox. Agent Toolkit tools are wired into the AI SDK.
  • The residential loop (November): the homeowner role, owner draws, change-order billing, the lien-waiver gate with signing evidence, the five-cell money strip, the settled Lopez reference job and the public #/demo judge seats.

The procurement features now sit behind GC sign-in. They aren't the subject of this entry.

Challenges I ran into

  • PayPal money states aren't binary. A created order isn't an authorization. A PENDING capture isn't funding. A submitted payout isn't settled, and UNCLAIMED isn't paid. The ledger only counts COMPLETED captures and SUCCESS payouts, and the UI says exactly which state you're in.
  • Retainage versus fees. After paying subs 90%, PayPal's fees leave the platform with less than the retainage it owes, so a sandbox release can fail with INSUFFICIENT_FUNDS. I added a sandbox-only top-up flow instead of hiding the failure.
  • Keeping the model out of the money. The rules engine sets each verdict and amount, the model only explains the evidence, and the UI labels model commentary separately from the GC's decision. The offline fallback had to be just as explicit, so a missing provider never looks like an AI review.
  • Recovery. At the start of November I lost a managed workspace and rebuilt from the public GitHub baseline into an isolated deployment, so I wouldn't overwrite a newer deployed schema.

Accomplishments that I'm proud of

  • Real sandbox receipts for the whole loop: authorization, partial capture, net payout, retainage, a paid owner draw and a paid change order. All of it ties back to one job ledger.
  • The overbilling catch is contract-aware, not arithmetic. It flags billing for excluded scope and unfunded milestones, and the GC's override is recorded per line with a reason.
  • Honest by construction: no fake success states, offline fallbacks are labeled, and the limits below are written down.

What I learned

Agentic payments need explicit approvals, code-computed money, idempotency and evidence that names both successes and limits. A passing deterministic fixture doesn't prove a model ran, and a green button doesn't prove PayPal settled.

What's next for TradePulse Pay

  • PayPal multiparty with the GC as seller (today one sandbox platform account is the merchant), a fee ledger and dispute handling.
  • A prime-milestone schedule that creates owner draws automatically, and in-app subcontract acceptance by the sub.
  • AgentID sign-in for subs' billing agents (the code exists but needs owner-approved client registration), so a sub's AI agent can file pay apps for it.
  • Validation with real remodel GCs beyond synthetic data.

Try it

No install or sign-up is needed. Everything runs on the hosted demo with shared sandbox accounts.

Demo accounts (every seat uses the same password):

PayPal sandbox card (guest checkout): 4032031427005060, exp 01/29, CVV 480, country United States. Choose to pay as a guest; don't create a PayPal account.

  1. Sign in. Open https://tradepulse-pay.asynchronope.tech/#/demo and click a seat button (GC, Subcontractor or Owner). It signs you in for you. To sign in by hand instead, use an email and the password listed above. The same details, plus the deployed commit hash, are also in the collapsed Manual sign-in and sandbox details block on that page. Every page other than #/demo asks you to sign in first, so start here. Use a separate browser window or profile for each seat.
  2. See a settled job (2 min, read-only). As the GC, you land on Approvals with the Lopez Kitchen money strip. Click View paid receipt on the settled Ortiz pay app to see the AI review, the GC override, the PayPal payout id and the lien waiver. For the full ledger of a finished guided run, stay signed in as the GC and open https://tradepulse-pay.asynchronope.tech/#/judge-demo/nx74k1sdcnsmqzvkr97kf0ts598hch6p. Signed out, this link shows the sign-in form; sign in with the GC email and password above.
  3. Run it live (5–10 min). As the GC, open Guided demo in the menu and click Run TradePulse Pay demo. It creates a fresh $55,000 sandbox subcontract. When the PayPal popup opens, fund Mobilization with the sandbox card above. The run then files an honest pay app and an overbilled one, reviews both with AI, runs the CSLB license check, approves, captures, pays out with retainage, and invoices a $1,850 change order to the Owner. Allow popups for the site.
  4. Other seats. Sign in as the Subcontractor ([email protected]) to see Ortiz Plumbing's settled Lopez pay app and money trail. Sign in as the Owner ([email protected]) to see job progress, the paid draw and change orders.
  5. Mirror. If the main domain is down, the same app is at https://cheery-axolotl-689.convex.site/#/demo with the same accounts.
  6. Self-host (optional). The README's Setup and run section covers Node 22, Convex, the PayPal sandbox app and webhook, and a Mistral key.

Limits, stated plainly:

  • PayPal is sandbox only. The data is synthetic, and the demo accounts are shared.
  • The Lopez reference job is read-only. Guided runs are the writable sandbox.
  • AgentID sign-in and the licensed AG Studio editor are not enabled on the hosted demo. The basic React dashboard works without them.
  • This isn't production. A real-money launch needs PayPal multiparty, a fee ledger and legal review.

Built With

  • agentmail
  • apimatic
  • cloudflare-pages
  • convex
  • firecrawl
  • kernel
  • mistral
  • paypal
  • paypal-agent-toolkit
  • paypal-js-sdk
  • paypal-orders-v2
  • paypal-payouts
  • paypal-webhooks
  • postman
  • react
  • tailwindcss
  • typescript
  • vercel-ai-sdk
  • vite
  • vitest
Share this project:

Updates

Submission history