Inspiration

A shelter coordinator needs 30 fragrance-free hygiene kits by Friday, with a budget of $175.

Today, fulfilling that request means hours of browsing supplier websites, comparing prices in spreadsheets, coordinating with donors, and hoping the supplier doesn't run out of stock after the money has already moved.

Crowdfunding moves cash, not outcomes. Nobody can easily verify what was promised, what was paid, and what actually arrived.

We wanted to build the opposite: a system where someone describes a need once, and AI agents coordinate the entire purchasing process while PayPal protects the sponsor's money until the goods are real.

Even when a supplier breaks their promise, the system should be able to recover automatically.

What it does

NeedMesh turns a community's needs into protected purchases, using AI to discover and coordinate suppliers while PayPal ensures sponsors' money is only captured when the goods are real.

  1. Describe the need in plain language or by voice. AI converts the request into a structured mission, separating hard constraints (such as fragrance-free, under $175, and delivery by Friday) from preferences. Every constraint is linked to the original words that produced it.

  2. AI-powered purchase planning. Specialized agents discover merchants, evaluate products, and construct an optimized purchase plan. Products that violate hard constraints are automatically excluded, and orders can be split across multiple merchants while remaining within budget.

  3. Competitive merchant marketplace. Public missions appear in a marketplace where merchants can submit offers. The Negotiation Agent evaluates offers and recommends counteroffers. A deal is finalized only when both parties explicitly accept it.

  4. Sponsor-specific funding through PayPal. Sponsors fund specific merchant orders rather than contributing to a shared wallet. Each merchant has a separate PayPal order, allowing sponsors to see exactly which purchase their money supports.

  5. Payment protection through authorization. PayPal orders are created using intent=AUTHORIZE. Payments are captured only after merchants confirm stock availability. If a supplier cannot fulfill the order, the authorization can be voided before the sponsor is charged.

  6. Automatic supplier recovery. When a supplier fails, the Recovery Agent checks the actual PayPal payment state, voids the authorization, identifies missing items, and replans the purchase with alternative merchants within the remaining budget.

  7. Verifiable mission receipts. Once the goods arrive, the recipient organization confirms fulfillment. The Mission Receipt records authorized, captured, never charged, refunded, and received amounts line by line, including PayPal transaction IDs.

PromiseTwin is integrated into every order. It maintains separate records of the original intent, merchant commitment, PayPal payment state, and delivery evidence. It detects broken promises and proposes remedies that must pass policy checks. It can also operate independently to protect individual business purchases.

Who it's for:

  • Nonprofits and community groups: shelters, food banks, schools, and mutual-aid organizations.
  • Sponsors and donors: individuals, local funds, and CSR programs that want to fund outcomes rather than cash pools.
  • Small merchants: suppliers looking for demand they can compete for through transparent bidding.
  • Small businesses: businesses that need protection when successful delivery matters more than simply completing checkout.

How it's different:

Traditional Approach NeedMesh
Crowdfunding collects money into a shared pool. Sponsors fund specific merchant orders. No pooled wallet.
Payment becomes final at checkout. Authorize first, capture after stock confirmation, and void if the seller fails.
Single-store wish lists without budget optimization. Multi-merchant purchase planning with hard-constraint and budget validation.
AI chatbots merely suggest products. AI agents execute workflows, with every financial action gated by a policy engine.
Delivery is accepted based on seller claims. Delivery counts only after recipient confirmation.

How we built it

  1. Monorepo architecture: Built using TypeScript with a NestJS 11 + Fastify backend, Prisma ORM with PostgreSQL, Next.js 15 / React 19 frontend, and shared Zod contracts.

  2. PayPal integration: Integrated PayPal Orders v2 with intent=AUTHORIZE and Payments v2 for authorization, capture, void, and refund operations. Also implemented shipment tracking, signature-verified webhooks with event deduplication, and the official @paypal/mcp server for read-only order verification.

  3. 11 specialized agents: Mission Planner, Merchant Matching, Commerce Planner, Negotiation, Funding, Policy Engine, PayPal Commerce, Recovery, Fulfillment, Reconciliation, and PromiseTwin. Every execution step records which agent acted and whether the operation was performed by deterministic rules, PayPal MCP, or AI.

  4. AI with guardrails: Planning, pricing, and policy decisions are implemented using deterministic, unit-tested code. Gemini (gemini-3.5-flash-lite) explains the purchase plan in natural language. Every numerical value generated by the model is validated against the planner's actual figures. If a mismatch is detected, a predefined explanation is displayed instead.

  5. Real-time, multi-user architecture: Every participant authenticates as an independent user through their own browser. A transactional outbox distributes mission events to each participant's organization through Server-Sent Events (SSE), with presence heartbeats to show who is online.

  6. AI Command Center: Built an interactive command center featuring an animated network showing requests travelling between users, AI agents, and PayPal; a live feed of AI reasoning; and an impact dashboard tracking authorized funds, captured payments, amounts never charged, and PayPal-verified transactions.

  7. Security: Implemented scrypt password hashing, HMAC-signed sessions, CSRF protection, origin validation, tenant isolation, and prompt-injection protection. Untrusted merchant instructions are explicitly ignored rather than followed.

Challenges we ran into

  1. Protecting payments without becoming an escrow provider. We needed to protect sponsor funds without holding money ourselves. PayPal's authorize-then-capture workflow provided the mechanism: funds are authorized first and captured only when fulfillment conditions are satisfied. NeedMesh never holds the money.

  2. MCP could read but not void payments. The PayPal MCP server does not expose a tool for voiding authorizations. We addressed this by separating responsibilities: read operations go through MCP, while write operations use PayPal REST APIs. The execution timeline clearly identifies which interface handled each operation.

  3. LLMs and financial accuracy don't mix. Early AI explanations occasionally invented prices and other numerical values. We moved all financial calculations into deterministic code and introduced validation that rejects explanations containing numbers not produced by the purchase planner.

  4. Free-tier AI reliability during live demos. The Gemini model we initially planned to use became unavailable for new API keys, while the API occasionally returned overloaded (503) responses. We implemented a one-time retry mechanism, strict request budgets, and graceful fallback explanations so a mission never fails simply because the AI service is temporarily unavailable.

  5. Coordinating multiple organizations in real time. The organization, sponsors, and merchants operate under separate organizational accounts. Each participant needs real-time updates without accessing information belonging to other organizations. We solved this by distributing transactional outbox events separately to each participant's organization.

  6. Keeping demonstrations honest. Every simulated component, including fictional merchants, simulated stock, and the demo clock, is explicitly labelled in the UI. This ensures simulated activity is never mistaken for an actual PayPal transaction or real-world fulfillment event.

Accomplishments that we're proud of

  1. End-to-end PayPal Sandbox integration: Successfully demonstrated order creation, authorization, capture, stockout-triggered voiding, replanning, and final receipts.

  2. Self-healing payments: When a supplier fails, the sponsor is never charged. The system releases the authorization and finds a replacement within budget without requiring anyone to redo the entire process.

  3. Multi-party live demonstration: Organizations, sponsors, and merchants interact through independent browsers and see updates in real time.

  4. Transparent AI execution: Every action identifies the responsible agent and whether it was performed by AI, deterministic rules, or PayPal. AI-generated financial figures cannot bypass validation.

  5. 120 automated tests: Supported by API smoke scripts and two-browser end-to-end tests using Playwright.

What we learned

  1. Agentic commerce requires constrained autonomy. An AI agent's authority must be narrower than its intelligence. AI proposes, policy decides, and PayPal remains the source of truth for payment state.

  2. Authorization holds are underutilized. They transform traditional pay-and-pray transactions into pay-when-it's-real workflows.

  3. Transparency builds trust. Showing which agent acted, which engine made the decision, and which PayPal operation occurred was more valuable than simply presenting polished AI-generated explanations.

What's next for NeedMesh

  1. Real merchant onboarding: Onboard local suppliers and integrate PayPal checkout through the JavaScript SDK.

  2. Verified organizations: Introduce real KYC and registry verification before allowing missions to become publicly available.

  3. Large-scale catalog discovery: Expand beyond predefined catalogs to discover suppliers, compare offers, and optimize purchases across a much larger merchant network.

  4. Proactive missions: Analyze historical mission data to forecast shortages and recommend new missions before essential supplies run out.

  5. Recurring sponsorships: Enable sponsors to automatically fund recurring outcomes, such as keeping a shelter stocked with hygiene kits every month.

Built With

Share this project:

Updates

Submission history