Penny

• 

  Penny(mascot)

Inspiration

Most cashback programs pay out tiny amounts, a few cents here, a dollar there, and that money just sits forgotten in an app balance. A $1.80 payout sent on its own would lose roughly 28% to fixed fees if you tried to invest it. We asked: what if that spare change could quietly pool up until investing it actually makes sense, and then an AI agent could put it to work, safely? Penny is our answer: a store where you shop with a real PayPal sandbox checkout, earn simulated cashback, and watch an AI agent grow the pooled pot into a broad-index paper portfolio.

What it does

Penny is a web app with a store, an AI investor, and a live dashboard:

• Shop and earn. Buy products through a real PayPal sandbox checkout (Orders API v2, capture, webhooks). Penny credits simulated cashback (2% by default) into a "pending pot". A toast confirms every credit.
• Pool, don't trickle. A fee-aware threshold decides when the pot is worth investing: it waits until fees would eat less than a set fraction of the trade, or until cash has waited too long.
• The agent invests. Once the threshold is hit, an LLM agent (Groq, OpenAI-compatible tool calling) proposes orders through a deterministic policy engine. Approved orders go to a paper broker (Alpaca paper trading, or a built-in simulated market). Every trade comes with a one-line, template-generated explanation.
• Human in the loop. Orders above a cap need your approval, and every approved order has an undo countdown before it executes.
• Watch it grow. A floating Penny widget opens a dashboard: cashback collected, holdings (AG Grid), a value-vs-money-put-in chart (AG Charts), and a withdraw button that pays out through the PayPal Payouts API, selling positions pro rata if you ask.

Everything is fully disclosed as a simulation: no real cashback provider, no real securities, no financial advice, and seeded demo history is clearly labelled.

How we built it

• Backend: FastAPI, with everything money-related done in decimal.Decimal quantized to cents, never floats. SQLite in dev, Postgres on Render.
• PayPal: Orders API v2 for the store checkout, signature-verified webhooks on the raw body (idempotent by capture/event id, so a capture is credited once even if both paths fire), and the Payouts API for withdrawals, including the ERRPYO002 negative-test flow.
• The core safety idea: the model proposes, rules decide. The LLM never executes anything. It calls tools; every proposed order passes through policy.validate(), a pure, deterministic, unit-tested function that enforces an ETF-only allowlist, allocation bands, trade caps, pot limits, buys-only (sells only for withdrawals), and quote freshness. Explanations are templates over ledger facts, and any LLM sentence containing a number no tool returned is thrown away. If the model misbehaves, a deterministic planner proposes the same orders through the same gate; if the LLM is down, a rule-based mode takes over and the response says so.
• Frontend: React 18 + TypeScript + Vite, with AG Grid and AG Charts (Community, MIT) for the dashboard. Secrets never reach the browser bundle; only VITE_ variables do.
• Integrations: Groq as the agent LLM (with exponential-backoff retries and malformed-tool-call recovery), Alpaca paper trading via alpaca-py with a simulated broker fallback, and Channel3 for server-side "better deals" product search.
• Quality: 133 backend tests run with no network (in-memory SQLite plus fake broker, PayPal, LLM, and Channel3), a type-checked frontend build, a Postman collection covering the whole API in demo order, and a render.yaml blueprint for one-click hosting.

Challenges we ran into

• Making the LLM safe with money. Our first instinct was to let the model place trades directly; we replaced that with a hard policy gate and learned to design tool schemas so the model can't invent tickers, amounts, or trades the rules would have to reject anyway.
• Idempotency across two paths. A capture can be credited by the checkout flow and again by a webhook; we had to design a shared dedupe key (capture:<capture id>) so cashback is credited exactly once.
• Quote staleness. Alpaca quotes go stale outside US market hours, which broke the policy engine's freshness rule; we made quote age a configurable policy input and taught the simulated broker to fill the gap for demos.
• Band validation deadlock. An empty portfolio could never place its first order without violating an allocation band, so we validate all orders from one plan together and allow buys that move a drifted portfolio strictly closer to target.
• Honest demo data. We wanted the dashboard to look alive without faking anything user-visible, so seeding only runs on an empty database and everything is labelled as simulated.

Accomplishments that we're proud of

• A complete, working loop from checkout to cashback to AI-invested portfolio to withdrawal back to PayPal, all in one app.
• 133 passing tests over the entire money path with zero network access, so the safety-critical core is genuinely unit-tested.
• An agent architecture where the LLM adds explanation and flexibility but can never bypass the rules: the policy engine is pure, deterministic, and always the last word.
• A dashboard that makes the whole story visible in seconds: the pot, the threshold, the undo countdown, the one-line explanations, and the profit/loss chart that correctly accounts for withdrawals.

What we learned

• "The model proposes, rules decide" is a practical, testable pattern for putting an LLM near money: deterministic validation, templated explanations, and planner fallbacks remove most of the risk of generative agents.
• Fintech plumbing is mostly edge cases: idempotency, webhook signature verification on the raw body, fee-aware thresholds, and Decimal-everywhere accounting matter more than the happy path.
• Fee drag is the real reason small amounts stay uninvested, and pooling with a fee-aware threshold is a simple, honest fix.
• Clear disclosure builds trust: labelling what is simulated, what is paper, and what is demo data made the demo easier to explain, not harder.

What's next for Penny

• Real cashback: partner with an affiliate/cashback network so the pot is fed by real rewards instead of a simulated rate.
• Smarter investing: dividend-aware paper simulation, rebalancing on drift, and optional recurring contributions from real funds.
• Richer agent supervision: editable risk profiles with live what-if previews, per-order reasoning traces, and configurable approval rules.
• Multi-user: proper accounts so Penny can run as a personal micro-investing companion, with notifications when the pot is ready. #Creator's Note: -I created fallback systems for almost every point of failure, since most of the APIs used are free and can expire or change over time, but the judges can still see a working version of the concept in the worst-case scenario. -The message in the top-right corner, "PayPal not configured / PayPal sandbox," is to assure the user that no real transaction is taking place.

Built With

• alpaca
• channel3
• paypal
• render