PayPal Ledger Analyst

Ask your PayPal ledger questions in plain English; an AI agent shows its SQL and only acts on PayPal after you confirm.

Comment

Inspiration

Small merchants run their business in PayPal, but simple questions like "which invoices are overdue?" or "where are my refunds coming from?" still mean exporting CSVs and building spreadsheets. Then you chase customers by hand. We wanted an AI teammate you can just ask, that shows its work, and that never touches money or customers without your approval.

What it does

  • Answers plain-English questions about a PayPal merchant's orders, captures, refunds, and invoices.
  • Every answer shows the generated SQL, a result table, and a chart when it helps, so every number can be checked.
  • The agent can propose one PayPal action, such as sending reminders for overdue invoices (or a refund). It shows the exact invoices, amounts, and PayPal endpoint. Nothing happens until the user clicks Confirm. Then the server calls the PayPal Invoicing v2 remind endpoint and shows a live result log (for example, 5/5 reminders → 200 OK in the sandbox).

How we built it

  • PayPal sandbox REST APIs: a seed script uses Orders v2, Payments v2 (captures, refunds), and Invoicing v2 to create a realistic merchant history. A loader syncs it into DuckDB tables (orders, captures, refunds, invoices).
  • AI agent: Claude (Anthropic API) with two tools. run_sql runs a read-only query over the ledger. propose_action returns a signed pending action and has no side effects.
  • Backend: Python FastAPI on Vercel serverless functions with in-process DuckDB. /api/ask runs the agent and /api/confirm carries out a confirmed action against PayPal.
  • Frontend: plain HTML/JS. It has a question box, sample questions, a SQL panel, an SVG chart, a table, an action card, and a sandbox log.
  • Cost and abuse guard: persistent spend tracking and per-IP rate limits in Supabase, with a hard spend cap on the hosted demo.

Challenges we ran into

  • Making SQL from an LLM safe: we built a SELECT-only guard and a row cap, and turned off DuckDB external access.
  • Keeping actions human-gated end to end. Actions are signed tokens that are only honored by /confirm, so the model can never call PayPal directly.
  • Seeding sandbox data that looks real: staggered invoice due dates, partial refunds, and tying captures and refunds back to orders.
  • Running a public AI demo on a fixed budget without hurting the judge experience.

Accomplishments that we're proud of

  • A working end-to-end loop on the real PayPal sandbox: question → SQL → table/chart → proposed action → Confirm → live 200 OK responses from PayPal Invoicing.
  • Every answer is checkable, because the SQL and the raw rows are always shown.
  • Small, readable code with tests for the SQL guard, action signing, and cost guard.

What we learned

  • PayPal's Orders, Payments, and Invoicing APIs map cleanly to an analytics schema once captures and refunds are linked to orders.
  • Agents get much more trustworthy when "read" and "act" are separate tools with different permissions.
  • Showing the SQL builds more user trust than any amount of explanation.

What's next for PayPal Ledger Analyst

  • OAuth "Log in with PayPal" so merchants can connect their own accounts (read-only by default).
  • Incremental sync through PayPal webhooks and the Transaction Search API.
  • More confirm-gated actions: partial refunds, invoice drafts, and payment-link follow-ups.
  • Scheduled digests, for example a weekly overdue-invoice report with one-click reminders.

Built With

Share this project:

Updates

Submission history