Inspiration

Freelancers and small merchants often see money in their PayPal balance and assume it is available to spend, save, or allocate. However, irregular income, upcoming operating expenses, potential refunds, and unresolved disputes can make that balance misleading.

This inspired us to ask a simple but important question:

How much of my current PayPal balance can I actually afford to set aside without putting my business at risk?

Most financial dashboards focus on displaying balances and transactions. We wanted to go further by helping merchants understand their actual financial position and make more informed decisions about their available cash.

What it does

Surplus is an AI-powered financial insights platform designed for PayPal-paid freelancers and small merchants.

It combines a deterministic financial engine with an AI-powered advisor to help users understand their financial runway and estimate how much money may be safely available.

Key features include:

  • 12-Month Cash-Flow Analysis: Understand historical income patterns and current financial activity.
  • Risk-Aware Cash Reserves: Account for operating expenses, income volatility, expected refunds, and unresolved disputes.
  • Safe Surplus Estimation: Estimate the amount potentially available after accounting for required reserves.
  • Staged Allocation Plans: Explore cautious allocation bands based on the merchant's financial risk profile.
  • What-If Simulations: Test scenarios such as income shocks, delayed payments, and unexpected expenses.
  • AI Financial Advisor: Ask questions and receive clear explanations of financial results based on verified calculations.

How we built it

We built Surplus as a modular full-stack application using:

  • Frontend: Next.js, React, and TypeScript.
  • Backend: Node.js and Express.
  • Database: SQLite with WAL mode.
  • AI Integration: Gemini 2.5 Flash and GPT-4o-mini as a fallback through the Vercel AI SDK.
  • Data Visualization: Recharts and AG Grid Community.
  • Financial Engine: Deterministic calculations supported by property-based testing.

The application integrates with the PayPal Developer Platform and Sandbox environment, supporting OAuth 2.0 authentication, transaction and balance retrieval, dispute information, orders, payment capture, webhook signature verification, and a read-only PayPal MCP integration boundary.

A key architectural decision was separating financial calculations from AI generation.

The financial engine calculates all monetary values, while the AI advisor explains those results using approved evidence. A grounding and safety validation layer checks generated responses to reduce unsupported figures and unsafe financial claims.

Challenges we ran into

One of our biggest challenges was balancing AI-powered assistance with financial reliability and safety.

We needed to ensure that the AI advisor could explain financial results without inventing numbers, changing calculated values, or making unsupported financial recommendations.

We addressed this by:

  • Keeping all financial calculations within a deterministic engine.
  • Separating financial logic from AI-generated explanations.
  • Grounding AI responses in approved financial evidence.
  • Validating generated responses against trusted calculation results.

Another challenge was designing a useful reserve and surplus estimation approach that considers multiple financial risk factors rather than simply subtracting expenses from the current balance.

Accomplishments that we're proud of

We are particularly proud of:

  • Building a complete financial insights concept around the PayPal ecosystem.
  • Combining deterministic financial calculations with an AI-powered conversational advisor.
  • Designing a risk-aware surplus estimation approach that considers operating needs, income volatility, refunds, and disputes.
  • Implementing what-if simulations to help merchants explore potential financial scenarios.
  • Establishing a modular architecture that separates PayPal integrations, financial calculations, AI services, and the frontend.
  • Prioritizing financial transparency and AI safety instead of allowing an LLM to make financial decisions.

Most importantly, we transformed a simple balance dashboard concept into a tool that helps merchants understand what their money actually means for their business.

What we learned

Building Surplus taught us that adding AI to a financial application requires much more than connecting an LLM API.

Financial calculations must remain reliable, transparent, and independent of generated text.

We gained practical experience with:

  • Integrating the PayPal Developer Platform and Sandbox APIs.
  • Designing deterministic financial logic and testing its behavior.
  • Building AI-powered applications with the Vercel AI SDK.
  • Using evidence grounding and response validation to improve AI reliability.
  • Designing modular full-stack architectures.
  • Handling financial risk indicators and translating complex calculations into understandable insights.

We also learned how important it is to establish clear boundaries between what AI should explain and what the underlying system must calculate.

What's next for Surplus

We see several opportunities to take Surplus further:

  • Live PayPal Integration: Expand beyond Sandbox demonstrations toward secure production integrations.
  • Smarter Financial Forecasting: Improve cash-flow projections using historical trends and changing income patterns.
  • Personalized Risk Profiles: Adapt reserve calculations to different merchant business models and operating needs.
  • Advanced Scenario Simulations: Introduce more detailed scenarios involving seasonal income, recurring expenses, delayed payments, and unexpected disputes.
  • Improved AI Explanations: Make financial insights more personalized, interactive, and accessible while maintaining strict evidence grounding.
  • Broader Financial Integrations: Explore additional payment platforms to support merchants managing income across multiple sources.

Our long-term vision is to make Surplus a trusted financial insights companion that helps freelancers and small businesses move beyond simply seeing their balance to understanding their financial position and making more informed decisions.

Built With

Share this project:

Updates

Submission history