Inspiration

AI agents are becoming increasingly capable of acting on users' behalf. But when those actions involve money, capability alone is not enough. The real challenge is authorization: what exactly has the user permitted an agent to do, and how can we guarantee that it never exceeds those limits?

Most AI shopping demos focus on getting a model to discover products and initiate payments. We wanted to solve a harder problem: building an agent that can make useful shopping decisions without giving the AI control over the user's money.

We were also concerned about prompt injection. Product titles and descriptions come from external websites and must be treated as untrusted input. A malicious listing should never be able to override a user's budget or purchasing rules.

That led to Budgie's central design principle:

The LLM proposes. Deterministic code decides. PayPal executes.

What it does

Budgie is an AI-powered shopping agent that converts natural-language shopping requests into controlled purchasing decisions.

For example, a user can enter:

"Mouse under $50, auto-buy under $30."

The workflow is:

  1. Understand the mandate: Gemini converts the request into a structured mandate containing the product category, maximum budget, minimum rating, delivery constraints and auto-approval limit. Pydantic validates the output, and a grounding check ensures that budget values are actually supported by the user's request.

  2. Discover products: Budgie searches product listings through Channel3 and retrieves relevant candidates.

  3. Apply deterministic guardrails: A rules engine checks every candidate against the user's mandate, product constraints and monthly spending cap. Each product receives one of three decisions: auto_pay, needs_approval or reject, along with reasons.

  4. Rank eligible products: Gemini ranks and explains only the products that have already passed the deterministic rules. It cannot change their prices, override rejection decisions or authorize payments.

  5. Request approval and pay: The user selects a product. Products requiring additional authorization trigger an explicit confirmation step. Budgie creates a PayPal Sandbox order using the server-stored product price, redirects the buyer for PayPal approval and captures the payment after verification.

  6. Monitor spending: The Spending dashboard displays spending trends, monthly limits and recent orders. Audit events are retained to support traceability of pipeline decisions and payment operations.

How we built it

Backend and API

  • Python and FastAPI for the application backend and REST APIs.
  • Pydantic for structured validation of mandates and API data.
  • SQLite for users, shopping runs, orders and spending records.
  • Environment-based configuration for external API credentials.

AI and decision-making

  • Google Gemini for natural-language mandate parsing, product ranking and explanations.
  • Strict validation and budget-grounding checks prevent the model from inventing purchasing limits.
  • A deterministic rules engine independently evaluates products.
  • A fallback selection mechanism keeps recommendations functional when AI ranking is unavailable.

Product discovery

  • Channel3 for external product discovery.
  • A mock product-search fallback for reliable demonstrations when the external service is unavailable.

Payment security

  • PayPal Orders API in Sandbox mode for order creation, buyer approval and capture.
  • Server-side price verification: the backend uses the price stored during the shopping run rather than trusting a price supplied by the browser.
  • Strict authenticated access and order ownership checks.
  • Atomic order replacement: inserting a replacement order, updating the shopping run and superseding the previous order happen within a single database transaction.
  • Capture verification checks PayPal's completion status, capture status, capture ID, amount and currency before updating the local database.
  • Superseded orders cannot be captured through the application's capture endpoint.

Frontend

  • React, TypeScript and Tailwind CSS.
  • Lovable-assisted UI development, followed by manual integration with the backend.
  • Interactive product recommendations, approval dialogs, shopping comparisons, payment receipts and spending visualizations.

Authentication

  • Email/password accounts using PBKDF2 password hashing and signed authentication tokens.
  • User-specific access to shopping runs, orders and spending data.
  • Budgie never requests or stores a user's PayPal password.

Testing and development

  • Python, pytest, Vitest and production build verification.
  • Claude Code and Lovable assisted with implementation, while changes were reviewed and tested manually.

Challenges we ran into

1. Separating AI decisions from payment authorization

Our biggest architectural challenge was ensuring that an LLM could never directly authorize a purchase. We separated product ranking from purchasing decisions and moved all important constraints into deterministic backend code. Even if a product description contains instructions intended to manipulate the model, it cannot change the rules engine's decision.

2. Handling incomplete real-world product data

Channel3 returns real product listings, but delivery estimates are unavailable and ratings are missing for many products. Initially, our rules rejected too many candidates. We changed the treatment of missing information so that uncertainty leads to needs_approval rather than automatically rejecting a potentially suitable product.

3. Making PayPal capture reliable

We encountered redirect and CORS issues during payment integration. PayPal could approve an order without the application successfully completing the capture flow. We corrected the return flow so that PayPal redirects to the backend, which handles the capture and then redirects the user to the application.

4. Preventing duplicate and stale orders

We discovered that creating a new PayPal order when a user switched products could leave the previous order in a created state. That created a risk of an outdated order remaining eligible for capture.

We introduced a superseded-order lifecycle and atomic database replacement. If inserting a new order, updating the shopping run or superseding the previous order fails, the transaction rolls back instead of leaving partially updated payment state.

5. Authentication and account isolation

During integration, we strengthened authentication for sensitive endpoints. We removed reliance on client-supplied email identity and added server-side ownership checks so one user cannot access or capture another user's orders.

6. Integrating parallel development work

We divided development between team members working on different parts of the application, including ranking, rate limiting, frontend UI, spending and authentication. Integrating these changes was challenging because the original workspaces did not share the same Git history. We had to compare changes carefully, reconnect the project to the repository and preserve newer work while integrating the security improvements.

7. Environment and deployment issues

Missing environment variables, incorrect ports, host configuration and CORS settings caused several failures during local testing. We learned to verify the environment and backend logs before assuming an application-code problem.

8. AI-generated code required careful review

AI-assisted development helped us move quickly, but generated code sometimes introduced incorrect imports, JSX issues or tests that did not actually verify the intended behaviour. We adopted a workflow of reviewing changes, running automated tests, building the frontend and manually testing the payment flow after important modifications.

9. Working within free-tier infrastructure

Our free hosting environment introduces cold starts and database persistence limitations. We clearly distinguish seeded demonstration history from actual Sandbox orders rather than presenting sample spending data as real transactions.

Accomplishments that we're proud of

  • Built an end-to-end shopping workflow from a natural-language request to product discovery, deterministic evaluation, user approval, PayPal Sandbox payment and capture.
  • Established a clear separation between AI recommendations and payment authorization.
  • Implemented server-side price validation, strict authentication and order ownership checks.
  • Added atomic order replacement and superseded-order protection to reduce stale-payment risks.
  • Validated PayPal capture responses before updating payment records.
  • Built a spending dashboard with monthly limits and recent order information.
  • Added automated regression coverage for authentication, payment lifecycle, rollback behaviour, spending and application features.
  • Successfully verified the application through automated tests and a manual Sandbox purchase.

Final automated verification:

  • Backend: 68 passing tests.
  • Frontend: 23 passing tests.
  • Production frontend build: successful.
  • Manual PayPal Sandbox purchase and capture: successfully tested.

What we learned

  • In agentic systems, authorization and constraints matter more than simply connecting APIs.
  • LLMs are useful for interpreting intent and ranking options, but financial decisions should be enforced by deterministic, testable code.
  • External product descriptions must always be treated as untrusted input.
  • Missing information should lead to explicit user approval rather than assumptions.
  • Payment state must be managed transactionally, especially when users change their selections.
  • Authentication, ownership validation and server-side price checks are essential for payment workflows.
  • AI-assisted development can accelerate implementation, but human review, automated regression tests and real application testing remain necessary.

What's next for Budgie

  • PayPal OAuth integration for a more seamless account experience.
  • More advanced consent-based automatic payment capabilities, subject to PayPal's supported authorization mechanisms.
  • Better delivery estimates and product ratings through additional data providers.
  • Per-category budgets, recurring purchases and configurable spending alerts.
  • More robust rate limiting and persistent database infrastructure.
  • Expanded security testing and an independent security review before any production use involving real money.

Honest notes and limitations

  • All payments currently use PayPal Sandbox. No real money is transferred.
  • Channel3 does not provide reliable delivery estimates for every listing, so delivery-related constraints may require manual approval.
  • auto_pay means a purchase is eligible for the simplified approval flow within the user's configured limit; PayPal still requires buyer approval.
  • The Spending dashboard may combine seeded sample history with real Sandbox orders. Sample data is identified as such.
  • The current account system is a prototype authentication mechanism, not a production-grade identity provider.
  • The application is a hackathon prototype and requires further security, infrastructure and payment-compliance work before handling real-money transactions.

Built With

Share this project:

Updates

Submission history