Inspiration

Managing personal finances often feels fragmented. People track day-to-day spending in one app, split shared group expenses like dinners and road trips in another, and log in to separate portals to manage recurring subscriptions and digital payments. When conversational AI assistants entered the financial space, they introduced a major concern: autonomous agents executing payment actions silently or making inaccurate calculations based on hallucinated data.

We built PocketPilot to bridge this gap: an autonomous, tool-backed financial companion that unites personal budgeting, transparent group expense splitting, and PayPal Sandbox payments under one interface—grounded by strict security boundaries that prevent unauthorized transactions[cite: 7].

What It Does

PocketPilot acts as a unified financial dashboard and conversational co-pilot with four key capabilities:

  • Conversational Financial Analytics: Users can query spending naturally (e.g., "How much did I spend on food last month?"). Instead of generating ungrounded estimates, the AI orchestrator invokes deterministic, read-only database queries to return verified transaction totals[cite: 7, 21].
  • Zero-Loss Group Ledger: For shared trips and group bills, expenses are split using exact integer minor-unit math (paise/cents) to eliminate floating-point rounding errors. A minimum-transfer settlement engine computes optimal debt reconciliation plans to settle shared balances with the fewest possible transactions[cite: 7, 15].
  • Guarded PayPal Sandbox Checkout: When a user asks the assistant to pay a vendor or renew a subscription (e.g., "Pay CloudHost 25"), the copilot triggers an explicit confirmation gate rather than executing silently[cite: 21]. Users must review the recipient, currency, and amount before the system initiates the PayPal Orders v2 creation and capture workflow[cite: 4, 16].
  • Subscription Management: Tracks recurring services, tracks renewal cycles, and allows sandbox renewal checkout directly from the dashboard[cite: 14].

How We Built It

PocketPilot was built as a modern, decoupled full-stack application:

  • Backend: Built with Python and FastAPI, backed by SQLAlchemy with an automated SQLite zero-config fallback and PostgreSQL compatibility[cite: 7, 11]. It exposes REST endpoints for transaction aggregation, multi-member group ledgers, and payment lifecycle tracking[cite: 5].
  • AI Orchestration & Guardrails: Utilizes an OpenAI-compatible function-calling engine with custom tool definitions (get_spending_summary, calculate_split, and propose_payment_checkout)[cite: 21]. If network issues or API rate limits occur, the system falls back to a deterministic local rule-based router to maintain uninterrupted uptime[cite: 21].
  • PayPal Integration: Integrates server-side with the PayPal Orders v2 REST API using asynchronous HTTP client calls (httpx) to handle OAuth 2.0 authentication, order creation, order capture, and idempotent webhook signature verification[cite: 5, 16].
  • Frontend: A responsive multi-view dashboard developed with Next.js 14, React 18, and clean system UI components covering Home, Payments, Groups, Insights, Subscriptions, and Copilot tabs[cite: 10, 14].
  • Deployment: Hosted live on Render using coordinated web services for the Next.js client and FastAPI application server[cite: 5, 27, 31].

Challenges We Faced

  • Preventing Silent AI Actions: LLMs can be unpredictable when interpreting action-oriented prompts. Enforcing strict safety boundaries required decoupling the AI's proposal phase from actual execution, mandating a browser-level manual review banner before an order ID could be created[cite: 21].
  • Penny/Cent Rounding Discrepancies: Standard floating-point division often causes remainders to vanish or exceed the total bill when dividing among multiple people (e.g., $100 among 3 people). We resolved this by converting all balances to integer minor units, distributing remainders deterministically across participants, and verifying zero-sum balance nets with unit tests[cite: 15, 20].
  • Asynchronous Webhook Idempotency: Ensuring payment events weren't double-counted required building a database-level event log that tracks provider capture IDs and idempotently ignores duplicate incoming webhook payloads[cite: 5, 16].

Accomplishments We're Proud Of

  • Passing a full test suite verifying integer split arithmetic, debt settlement resolution, and end-to-end PayPal order creation/capture workflows[cite: 20].
  • Implementing a resilient AI layer that executes structured database queries and handles API rate limits without service interruption[cite: 21, 32].
  • Building a full-stack, dual-service architecture deployed live on Render with functioning PayPal Sandbox checkout capabilities[cite: 5, 27, 31].

What We Learned

  • How to design and structure real-world payment lifecycles using PayPal's Orders v2 and webhook verification APIs[cite: 5, 16].
  • Best practices for designing tool-calling AI agents with guardrails that ensure human-in-the-loop oversight for all financial actions[cite: 21].
  • Techniques for building clean, zero-rounding financial ledger math in distributed software systems[cite: 15].

What's Next for PocketPilot

  • Adding multi-currency auto-conversion using live exchange rate APIs.
  • Expanding split options from equal shares to custom percentages and itemized receipt parsing via OCR.
  • Integrating PayPal Subscriptions / Billing Agreements API for native recurring charges alongside standard Orders v2 checkout.

Built With

Share this project:

Updates

Submission history