FinSig

FinSig turns PayPal transactions into verified income explanations and a 30-day cash plan. Claude explains; code calculates every amount; AG Studio traces each insight to source records.

Comment

Inspiration

Freelancers get paid through PayPal, but a transaction feed cannot answer the questions that shape their next decision: Why did my income change? Which client caused it? What is likely to arrive or leave in the next 30 days? Generic finance dashboards show totals; generic chatbots can produce confident explanations that do not add up.

FinSig is a financial cockpit that makes those answers both useful and auditable. Its operating principle is simple:

Claude explains and proposes; code calculates and verifies.

What it does

FinSig turns PayPal records into three connected workflows:

  1. Read-only PayPal evidence. PayPal Transaction Search reads the sandbox merchant attached to the FinSig developer app. The live view reconciles a payment, refund, and PayPal fee to the cent, while an opening-balance correction is held for review instead of being counted as income.
  2. Verified income investigation. FinSig compares two months, decomposes the exact change by client, refunds, and fees, and connects every factor to the PayPal records behind it.
  3. A 30-day cash plan. Open invoices, payments pending in PayPal, confirmed recurring client work, detected subscriptions, and user-entered expectations become a forward view. Ambiguous income requires confirmation. One isolated expense is never promoted into a recurring renewal. Large upcoming expenses create in-app alerts.

A fictional 12-month freelancer history powers the full product demonstration. Live sandbox records are labelled separately and are never mixed with the sample analytics.

Why the AI can be trusted

Claude helps where semantic judgment is valuable:

  • it proposes a category for an unlabelled payment and quotes the exact source fields it used;
  • it explains income changes and the 30-day cash plan;
  • it powers FinSig's custom adapter for the AG Studio Agent Framework.

The model cannot change transaction amounts or silently publish a financial claim. Money is represented in integer cents and calculated by deterministic domain code. AI responses use typed schemas and must cite known metric IDs and record IDs. The server verifies referenced records, quantities, and comparisons before rendering a claim. Invalid claims are dropped; if nothing remains verifiable, the answer is refused. User confirmation is required before a suggestion changes workspace state.

PayPal integration

PayPal is the source of truth, not a decorative checkout button. FinSig uses OAuth client credentials and the Transaction Search API to read first-party sandbox merchant activity. The importer validates PayPal responses, preserves transaction and event identifiers, normalizes signed amounts and fees, rejects duplicate imports with stable keys, and keeps unknown event types in review. A sanitized reporting gate documents repeat-read stability and the capture/refund reconciliation.

This hackathon build does not claim to connect arbitrary PayPal accounts. Delegated merchant onboarding was not available to us from Ukraine, so the public demo uses FinSig's configured sandbox merchant and labels that boundary explicitly.

AG Studio as the investigation surface

AG Studio is not a separate settings screen or a grid dropped into the product. It is the core Income investigation workflow:

  • a custom Verified bridge widget explains the exact month-to-month change;
  • an AG Studio evidence ledger shows the PayPal records behind each factor;
  • selecting a factor cross-filters the ledger and supports record-level drill-through;
  • FinSig's design tokens drive a custom Studio theme and responsive authored layout;
  • Customize analysis opens the full Studio editor on the same investigation;
  • Studio's page and widget agents run through a custom Claude adapter, so a user can ask for a fee analysis and add a chart from the same governed dataset.

AG Grid also powers the Transactions ledger with filtering, sorting, export, and record detail. The result demonstrates custom widgets, theming, layout tools, cross-filtering, and the Studio Agent Framework—not only AG Grid or AG Charts in isolation.

How we built it

  • Next.js App Router, React, and TypeScript in a pnpm/Turborepo monorepo
  • PayPal Transaction Search API and sandbox merchant data
  • Anthropic Claude with structured outputs and server-side grounding checks
  • AG Studio, AG Grid, custom widgets, custom theme, and Studio Agent Framework adapter
  • PostgreSQL migrations managed by Flyway for the importer path
  • Render for the public application
  • GitHub Actions quality and deployment gates

The product boundary stays read-only: PayPal credentials and the Anthropic key remain server-side, no PayPal access token is persisted, and AI receives no payment tool.

Challenges we ran into

The hardest problem was not generating a plausible explanation; it was proving that every number in it came from the ledger. We separated semantic work from financial authority, designed a typed claim protocol, and made the server reject unsupported quantities and comparisons.

The second challenge was making AG Studio feel like a native product workflow rather than an embedded builder. The custom bridge, evidence drill-through, FinSig theme, and agent adapter all operate on one investigation model.

PayPal reporting also required careful handling of delayed availability, signed event amounts, fees, refunds, and account-level corrections. We recorded those decisions in a repeatable reporting gate instead of hiding them behind sample data.

Accomplishments that we're proud of

  • The September-to-October bridge reconciles $8,828.21 → $5,300.85, an exact −$3,527.36 change, down to client, refund, and PayPal-fee factors.
  • A factor in the custom AG Studio widget narrows the evidence ledger to the precise records behind it.
  • The 30-day plan distinguishes confirmed, pending, inferred, and excluded cash events instead of presenting a fake balance or profit forecast.
  • Prompted or malformed AI numbers cannot bypass the grounding boundary.
  • The public demo, source repository, migration workflow, CI gates, and sanitized PayPal evidence are available to judges.

What we learned

Financial AI becomes useful when it is given less authority, not more. The model is best at reading ambiguous descriptions, proposing structure, and explaining verified metrics. Deterministic code should own money, reconciliation, and publication rules. AG Studio made that split visible: the agent can reshape an investigation, while the ledger and verified bridge remain the evidence layer.

Honest limits and what's next

Today, the rich 12-month workspace is fictional sample data and the live read covers the sandbox merchant attached to FinSig. Workspace choices are stored in the browser and alerts are in-app. Next we would add PayPal statement import as a practical connection path, server-side multi-user workspaces, scheduled sync, and opt-in external alerts. The safety model remains the same: AI proposes; verified code decides what can be shown as financial fact.

Built With

Share this project:

Updates

Submission history