PayPilot

AI agents spot stock risk, negotiate with suppliers and close the books for small merchants, while a person approves every dollar and PayPal moves the money.

Comment

Inspiration

A small coffee shop owner is the growth analyst, the buyer and the accountant at once. Their PayPal data already says which product is selling fast and when it will run out, but turning that into a decision, then a negotiated purchase order, then a correct supplier payment takes hours they do not have. Stock-outs are noticed after they happen, suppliers are chased by email, and prices are haggled by hand.

We wanted AI agents that do this work end to end, without ever being trusted with the money.

What it does

PayPilot is an AI operations team for merchants who sell through PayPal. One customer sale starts a complete, human-approved workflow in seven steps:

  1. Sale. A customer buys coffee beans through PayPal checkout (Orders v2). PayPilot captures the payment, records the order and updates inventory. The browser return and PayPal's verified webhook both record the sale exactly once.
  2. Insight. PayPilot detects a 73% rise in demand and only 3.3 days of stock. Before any agent speaks, a deterministic engine sets the limits:

$$\text{max landed cost per bag} = \$18.00 \times (1 - 40\%) = \$10.80$$

  1. Negotiate. A buyer agent negotiates with three independent supplier agents, each with private pricing, over typed, HMAC-signed messages. The backend validates every offer against the policy; an out-of-bounds proposal is refused, not clamped.
  2. Approve. Agents can recommend but cannot spend. An Analyst who tries to approve gets HTTP 403. The Owner approves terms bound to a SHA-256 hash, so changing a cent voids the approval.
  3. Match. A partial delivery holds the payment. It is released only when the purchase order, goods receipt and invoice agree (three-way match).
  4. Pay. PayPal pays the supplier through Orders v2 on PayPal's official APIMatic-generated Server SDK, with the supplier as payee. The PayPal-Request-Id comes from the approval, so a retry can never pay twice.
  5. Reconcile. PO, receipt, invoice and capture agree to the cent. Inventory is revalued and the product margin moves from 35.6% to 44%, feeding straight back into growth analytics.

Around that loop:

  • Growth intelligence: opportunities found in PayPal Transaction Search data, measured with controlled experiments.
  • Finance: PayPal Invoicing, approval-gated cashback Payouts, and a subscription revenue radar with one-click failed-payment recovery.
  • Supply intelligence: product discovery and a conversational shopping agent on Channel3's live catalog.
  • Timeline: a Bryntum Gantt of every procurement, where a supplier agent's signed delay report moves the delivery and the PayPal payment that waits on it.

PayPilot architecture

Why PayPal is central

PayPal is the merchant's system of record and the only rail money moves on:

  • Orders v2 for checkout and supplier payments
  • Transaction Search for analytics
  • Invoicing and Payouts to reach customers
  • Subscriptions and verified webhooks for recurring revenue
  • PayPal's Agent Toolkit over MCP, connected read-only: 16 of its 46 tools are callable, and the 30 that create, pay or send are blocked in code before any request is made

Every PayPal record is labelled SANDBOX, LIVE or SIMULATED, so nothing simulated is ever presented as real.

How we built it

  • Backend: Python, FastAPI, SQLAlchemy 2 (async), PostgreSQL 16 with pgvector, Alembic. Money is Decimal end to end; limits, scoring, matching and revaluation are deterministic code, never an LLM.
  • Agents: three LangGraph workflows (growth investigation, procurement autopilot, a seven-agent Merchant OS), all ending at a human approval gate. They call a registry of 49 typed, permission-checked tools. Groq GPT-OSS-120B handles intent routing, narration and the buyer's negotiation strategy. pgvector stores agent memory. Every node has a deterministic fallback, so the product runs without an LLM key.
  • PayPal: supplier payments run on the APIMatic-generated paypal-server-sdk, written with the APIMatic PayPal Context Plugin. Our own REST client (OAuth caching, retries, idempotency, raw-body webhook verification) covers the other APIs. A labelled simulator lets anyone run the whole loop without keys.
  • Frontend: Next.js 15, React 19, TypeScript, TanStack Query, AG Grid and AG Studio, Bryntum Gantt and Scheduler.
  • Platform: a transactional outbox with HMAC-signed n8n automation, Redis for shared rate limits, caches and realtime pub/sub, and Langfuse traces. One Render Blueprint deploys the API, web app, Postgres, Key Value, n8n and an APIMatic developer portal for PayPilot's own API.

Challenges we ran into

  • Keeping AI away from the money. We moved every number into a deterministic policy engine, bound approvals to a hash of the exact terms, and made the agent tools for approving or paying always refuse.
  • Signatures across languages. Python writes 13.0 where JavaScript writes 13, so the agent protocol and n8n webhooks both sign a pinned canonical JSON form.
  • Real PayPal is stricter than a mock. The sandbox rejected currencies we assumed would work. The sandbox MCP server currently fails every tool call with Unsupported cache mode, which we surface as an error instead of pretending it worked.
  • SDK details. The APIMatic Context Plugin caught traps we would have shipped: a token fetch that hides a real 401, optional fields that are absent rather than None, and retry defaults that skip POST.
  • Sponsor components. Two copies of AG Grid blanked AG Studio until both were pinned to one version, and Bryntum needed one exact version and tier across all packages.

Accomplishments that we're proud of

  • A complete purchase-to-pay loop where every figure is reproducible and every money movement has a named human approver.
  • Agent-to-agent negotiation with real, persisted, signature-verified protocol messages.
  • A live PayPal sandbox supplier payment (create, buyer approval, capture) on PayPal's official SDK.
  • 535 backend tests, including the full procurement lifecycle through the real API, tenant isolation, RBAC denials and webhook verification. None of them need Docker or API keys.

What we learned

Agents are most useful when the boundaries are explicit. Deterministic code owns limits and money; agents own search, negotiation and explanation; people own the decision. That split also made the system far easier to test and to trust.

What's next

  • Live PayPal beyond the sandbox
  • Real supplier systems speaking our signed agent protocol
  • Scheduled dashboard reports
  • Channel3 product subscriptions, so recommendations react when a retailer changes a price or runs out

Try it

Built With

Share this project:

Updates

Submission history