Keus

Give an AI agent a budget and keep the approval. Keus shops with AI, enforces your spend policy server-side, and authorizes on PayPal sandbox only when you say yes.

Comment

Inspiration

Agentic commerce only works if people trust the agent with money. Today's options are extremes: hand the agent a card, or make it stop at "here is a link". We wanted the middle: the agent does the research and the paperwork; the human gives one informed yes; PayPal holds the funds; nothing is captured until a real business process says so.

What it does

Keus is a workspace where an AI shopping agent researches products, prepares a priced purchase, and hands it to a human for one-click PayPal approval, with limits enforced server-side and every hold voidable.

  • Agent workspace. Each user gets agents (a starter agent, "Scout", is created on first sign-in) with a role, a per-order cap and a daily cap set during a three-step onboarding.
  • Grounded shopping. Ask for a product; the agent searches the Channel3 catalog, compares options from retrieved data rather than memory, and can bundle up to ten lines with quantities.
  • Purchase review. When asked to buy, the agent produces a purchase review (merchant reference, unit price, quantity, line totals in integer cents) that waits for a human. Spending limits are enforced on the server against the full subtotal.
  • PayPal approval. "Review checkout" records consent in Keus; "Get PayPal approval link" creates an AUTHORIZE-intent PayPal order (Orders v2) from the stored mandate, never from client-supplied amounts. The buyer approves that one purchase in PayPal.
  • Verified return. On return, the server re-verifies amount, currency, merchant reference, item breakdown, user and session binding, and the current limits before requesting the authorization. The user lands back in the originating conversation, which now carries a verified checkout message; the agent receives it as server context on its next turn.
  • Human stays in control. Inspect, reconcile ("Recheck PayPal status") or void any hold from the UI. Cancellations and uncertain outcomes are never labelled as success. Capture is disabled.

How we built it

  • Node 24, a plain HTTP server and a vanilla front-end (no framework), libSQL/Turso with numbered migrations, deployed on Render (render.yaml in the repo).
  • PayPal: Orders v2 (create, approve, authorize), authorization lookup, void, idempotency keys, a server-side verification layer, webhook and return handling, and a chat-event bridge so payment state shows up inside the agent conversation.
  • AI: a provider-agnostic LLM layer (OpenAI-compatible and Anthropic Messages protocols) with admin-managed, encrypted provider keys; a tool-calling agent with product search, grounded comparison, basket and mandate tools.
  • Channel3 for product discovery (sample catalog fallback when no key is configured).
  • WorkOS for authentication: email and password with verification codes, Google and GitHub.
  • 539 automated tests (npm test), plus browser checks and real sandbox runs on the deployed app.
  • Architecture, purchase sequence, checkout state machine and trust model are documented with diagrams in docs/ARCHITECTURE.md.

Challenges we ran into

  • We changed the trust model mid-build. The first iteration verified the agent's access to PayPal once (a saved-wallet / Vault style setup) and then let the agent spend inside its limits. Testing it against real sandbox flows made the problem obvious: a single up-front consent cannot tell the person what they are actually paying for. We rebuilt checkout so that every purchase goes through PayPal approval of that exact order, the server re-verifies amount, items and current limits on return, and only an authorization is created. That is more friction per purchase, and it is the point: the human sees and approves each checkout, and nothing is ever captured by the agent.
  • Making money movement fail closed: unsupported currencies, provider errors, missing credentials and expired approvals all had to end in an explicit, honest state, never a simulated success.
  • Reconciling uncertain outcomes (tab closed mid-approval, provider timeout) without ever creating a second hold.
  • Keeping amounts trustworthy end to end: the server computes every total, the PayPal order carries the matching breakdown, and authorization is verified against the stored mandate.
  • Cross-account isolation and session binding on every checkout endpoint.

Accomplishments that we're proud of

  • A complete loop a judge can run in five minutes on the sandbox: research, review, PayPal approval, verified hold, void.
  • Operational maturity for a hackathon project: encrypted database backup and restore, rollback and roll-forward deploy drills, secret scanning and key rotation, migration drift checks.
  • Every one of the dozens of sandbox authorizations created during testing was voided; the system never leaked a hold.

What we learned

Trust is a product feature. Most of the engineering went into what the agent is not allowed to do, and into making every outcome legible to the person approving it.

What's next for Keus

Capture on confirmed fulfilment, refunds through the same verified path, PayPal Vault for returning buyers who opt in, richer merchant data via Channel3, and multi-agent budgets for small teams.

Try it

Everything runs against the PayPal sandbox. Capture is disabled; no real money moves.

Built With

Share this project:

Updates

Submission history