Hearthline

Disaster recovery on PayPal: AI agents haggle with local stores, give within donors' limits, and send cash within hours of an evacuation order, while people approve every dollar.

Comment

Inspiration

When a wildfire or flood takes a home, help arrives fast and in the wrong shape. Families get cash they can't stretch, donors can't see where their money went, copycat fundraisers appear within hours, insurance claims wait on inventories nobody made, and the local shops a town depends on close for good. We wanted one place where help is specific, traceable and hard to steal, with PayPal moving every dollar.

The numbers behind it:

  • In one year, 3 to 3.9 million US adults were displaced from their homes by a disaster (GAO-26-108280, May 2026, citing the Census Bureau).
  • In the two weeks after Hurricane Milton, up to 77% of daily calls to FEMA's helpline went unanswered, and waits peaked at 2 hours 14 minutes (GAO-26-108154, April 2026).
  • 1.9 to 2.7 million displaced adults got a possible scam offer within a month of a disaster (GAO-26-108280).
  • Only 47% of US homeowners have a home inventory, the list an insurer asks for after a loss (Insurance Information Institute, 2023).
  • 69% of surveyed households who lost their home in the 2025 Los Angeles fires are underinsured, by $542,000 on average (United Policyholders, March 2026; a self-selected survey).

What it does

Hearthline follows one fictional family, the Riveras, through the made-up Sablewood Fire:

  • Prepare. Elena photographs her home before the fire. The Inventory agent lists what it sees, Channel3 prices it, and the dated inventory in AG Grid exports to Excel for a claim; a pivot chart shows what each room held. National Weather Service alerts warn her when a disaster nears.
  • Cash in the first 72 hours. When an official evacuation order or a FEMA declaration covers the zone, every household that prepared (verified, with an inventory from before the disaster) gets $250 plus $50 per person. Rules prepare one PayPal Payouts batch, Sentinel holds back anyone with warning signs, and one person approves it. Elena sees the money on her Aid page within minutes.
  • A fund that's ready before the fire. Donors give $10, $25 or $50 a month to a readiness fund with PayPal Subscriptions. When the first-72-hours batch is approved, the fund pays what it can and general cash aid pays the rest, and the panel says which before anyone approves.
  • Know what's next. Each family's home page lists their open steps, soonest first: approvals waiting on them, FEMA's 60-day application window, their insurance policy's own deadlines, crew visits. The recovery navigator explains the list in their language, reads it aloud and answers questions by voice. Code computes every date.
  • Respond. The family's Rebuild Registry lists exactly what they need, and donors pay with PayPal, Venmo or Pay Later. Family and friends abroad give in their own currency (Mexican or Philippine pesos, euros, Canadian dollars, pounds); PayPal converts it and the family receives dollars, recorded at PayPal's own rate. When an item is funded, the Shopper agent buys it, and nine spending rules in code decide whether it may, including California's 10% price-gouging limit.
  • Agents negotiate. Before web stores, the Shopper asks the town's reopened stores for quotes. Each store sells through its own pricing agent, bounded by the owner's lowest price and stock. The agents talk over MCP, the Shopper may counter once, and it buys the best price within its limit. The family can read the whole exchange.
  • Give automatically. A donor saves their PayPal account once with PayPal Vault and sets limits: where, how much per gift and per month, and for what. When verified families need help, the giving agent gives within those limits with no checkout and explains each gift. Stopping it deletes the saved account at PayPal.
  • Stop scams. The Sentinel agent flags a copycat registry. Two reviewers reject it, and every donor is refunded through PayPal.
  • Watch prices. A public Price Watch compares essential prices with what they cost before the disaster, using Channel3's price history, and charts the biggest rises against California's 10% legal limit.
  • People approve money. Cash aid is reviewed at a depth that scales with risk, then paid through PayPal Payouts to the family's own PayPal account, connected with Log in with PayPal.
  • Claim. The Policy agent reads the insurance policy, and Hearthline builds the contents claim from the inventory with the policy's limits applied. The adjuster pays with PayPal, and the money reaches the family in minutes instead of a mailed check.
  • Rebuild. A contractor's plan sits in escrow in a Bryntum Gantt. Each milestone is paid after the Site agent checks the photos and the homeowner approves. When a step runs late, the contractor tries it on the chart first: the Gantt's scheduling engine moves every step that waits for it, and shows the critical path and each step's days to spare. Once the contractor gives a reason, the family sees the new move-in day beside the plan they accepted, why it moved, and which escrow payments move with it.
  • Reopen. Closed businesses sell gift cards and monthly plans through PayPal Subscriptions. The money is released step by step, and refunded if the business misses its reopening date.
  • Run the response. The relief organization's Command Center shows 2,000 households in AG Grid's server-side row model and on a live map that follows the grid's filters (first-72-hours payments pulse as they land), sends batch cash aid that two people approve, answers PayPal disputes, and checks its books against PayPal's own records. Its dispatch agent plans tomorrow's crew visits for every waiting request on a Bryntum Scheduler Pro: code works out urgency, free hours and every drive, the agent picks the crew and the order and says why, and each visit shows as a ghost bar until a person accepts it.
  • Real disasters. Staff can open any disaster FEMA declared in the last four months, or any severe National Weather Service warning. Its counties, drawn from the Census Bureau's shapes, become the zone, and first-72-hours aid is proposed for the households there that prepared.

Everything works in English, Spanish, Chinese, Tagalog and Vietnamese.

How we built it

  • Backend: Python, FastAPI, SQLAlchemy and Alembic on Postgres, with a double-entry ledger for every money movement and a hash-chained audit log for every decision.
  • Frontend: React, TypeScript and Vite, with AG Grid Enterprise and five Bryntum views.
  • PayPal: Orders v2 through PayPal's APIMatic-generated Server SDK; JS SDK v6 buttons for PayPal, Venmo and Pay Later; Payouts; Subscriptions; Disputes; shipment tracking; signed webhooks; Log in with PayPal; Subscriptions for the readiness fund; Orders in five other currencies with PayPal's conversion read from the capture; Vault and merchant-initiated Orders (giving mandates) and Transaction Search and Balances (the books), both through APIMatic's PayPal Python SDK and integrated with APIMatic's PayPal Context Plugin; and PayPal's MCP server for "Ask PayPal".
  • AI: eleven agents on Google Gemini, with free OpenRouter models as a fallback. They prepare evidence, choose within limits and negotiate (the Shopper and the stores' pricing agents talk over an MCP server). Code enforces the rules, and people approve money.
  • Public data: OpenFEMA's disaster declarations, the National Weather Service's alerts and the Census Bureau's TIGERweb county shapes for real disaster zones; OpenStreetMap for the live map; the ECB's reference rates for estimates in a giver's currency.
  • Open to other agents: Hearthline's Public API and MCP server let another AI agent find a family's needs and prepare a PayPal gift for a person to approve.
  • Shipping: deployed on Render from a Blueprint, with Neon Postgres. 256 backend tests run on every push in CI, 28 browser checks make real sandbox payments against the live site, and a nightly check resets the hosted demo and uses it the way a judge would.

Challenges we ran into

  • The sandbox can't buy from real stores. Channel3 finds real products; the Shopper then pays a stand-in retailer account through Payouts. A local store is paid to its own PayPal account.
  • Checks against the live site found the API freezing on Render's small free instance: three upload endpoints made AI calls on the server's event loop, the health check timed out and the server restarted. We moved that work off the loop and added a test that fails if it comes back.
  • Some bugs appeared only on Postgres in production, such as a 43-character PayPal account ID in a 40-character column. Our tests now enforce column lengths the way Postgres does.
  • Four Bryntum products in one app crashed when a second one loaded. Bryntum's thin packages fixed it.
  • A rebuild delay has to say the same thing on the chart and on the server. Steps still to come are scheduled by the Gantt's engine (no earlier than planned, after what they wait for), and the server applies the same rules itself, so the contractor's preview and the family's notice always agree; the panel shows when they do.
  • Asking the dispatch agent for exact times made it drop jobs it thought overlapped. Now it chooses the crew and the order, and code works out the times so no crew is booked twice.
  • Saving a PayPal account and charging it later needed care: a merchant-initiated order requires a PayPal-Request-Id, and PayPal deduplicates on it, so each gift is claimed in our database before PayPal is called and can never be paid twice.
  • Census county shapes are generalized one county at a time, so a merged zone had slivers between neighbours. We close the gaps before merging and repair invalid shapes.
  • A gift in pesos arrives at a US account converted: PayPal reports its fee in pesos and the dollars it keeps after conversion. We record the gross at PayPal's rate and the fee as the difference, so our ledger equals what PayPal holds to the cent.
  • PayPal's Transaction Search reports with about a three-hour lag, so new ledger entries show as waiting rather than missing.
  • Recording the demo video found one more: a gift in pesos for "the rest" of an item landed $1.24 short, because the sandbox's exchange rate was 3.5% worse than our estimate. The item never counted as funded, so the Shopper never bought it. Now a gift from abroad that set out to cover the rest and lands within 2% funds the item.

Accomplishments that we're proud of

  • Every dollar can be traced: from a donor's PayPal payment, through the ledger and the Shopper's rules, to a store's PayPal account and the family.
  • AI never moves money on its own. Sentinel can only raise how many people review a case.
  • Eleven PayPal APIs work together end to end in the sandbox, with real payments in our automated checks.
  • One person's approval can pay every prepared family within hours of an evacuation order, and Sentinel still holds back the suspicious ones.
  • It works on a phone, in five languages, with WCAG AA contrast.
  • It has a written threat model (SECURITY.md): what's protected, the trust boundaries, what stops each kind of fraud with a link to the code, and the gaps we know about. Every push runs the tests, lint and a database migration check in CI.

What we learned

  • Let the model choose within rules that code enforces. The Shopper picks the product; code decides whether it may buy.
  • Test against the real deployment. The hosted site found bugs that local runs never did.

What's next

  • Bridge funding until insurance pays, offline use when networks are down, corporate gift matching, and a tax worksheet for disaster losses.
  • Checking out with real retailers instead of the sandbox stand-in.

Built With

Share this project:

Updates

Submission history