Inspiration

Everyone wants an agent that can buy things for them. Nobody wants an agent with their wallet and no limits. The missing piece is not the shopping, it is the mandate: a precise, revocable statement of what the agent may spend, on what, where, and when it must ask. We built the mandate first and the shopping around it. And we built the agent to be frugal by design, because an agent that wastes your money is worse than no agent at all.

What it does

  • You describe a mandate in plain words. "Keep the office stocked with ink and paper, up to $60 per purchase and $150 a month, only from Staples or Office Depot, ask me before anything over $40, expires at the end of the month." Gemini turns that into a structured policy you can read and edit before you accept it.
  • You consent once, in PayPal. Errandly creates a PayPal setup token, you approve it on PayPal's page, and your wallet is vaulted as a payment token tied to that mandate. Revoking the mandate deletes the token at PayPal. We never see or store a card.
  • You give the agent an errand. "We're out of copy paper, get 5 reams." It searches real products through Channel3, picks an offer, and proposes a purchase.
  • Code decides, not the model. A deterministic policy engine decides what happens next: pay now, pause for your approval, or refuse. Every check it ran is shown: per-purchase cap, period spend, purchase count, categories, merchants, expiry, currency.
  • Frugal by construction. Search results are pre-filtered to the price cap and the remaining budget, the agent must pick the lowest total price among genuine matches, it buys one unit unless told otherwise, and an errand in a category the mandate clearly blocks or does not allow is refused before a single search runs. Everything else is checked by the policy engine when the agent proposes a purchase. If nothing fits, it says "Nothing found" and spends nothing. We would rather your agent come back empty-handed than spend your money on the wrong thing.
  • Small in-policy purchases complete with nobody present. A purchase that passes every check and costs no more than the auto-approve threshold is charged merchant-initiated against the vaulted wallet through PayPal Orders v2 with stored-credential fields. One that passes every check but costs more than the threshold waits for a tap. A proposal that breaks the mandate is refused, not held. Each run shows a timeline: the searches with top candidates and prices, the proposal, the policy verdict, and the PayPal order and capture ids.

How we built it

Next.js 16 serves the UI and the API. Mandate parsing uses the Vercel AI SDK's structured output against a zod schema. The agent loop is a generateText tool loop with a hard step limit and a small, explicit tool set: product search (Channel3, capped at three searches per errand, with a labelled demo catalog when no key is set), refuse task (for errands in a clearly disallowed category, checked before any search), propose purchase (which runs the policy engine), report no match, and PayPal read tools from the PayPal Agent Toolkit.

Consent uses PayPal Payment Method Tokens v3: a setup token with a merchant, unscheduled-prepaid usage pattern, exchanged for a payment token after approval. Charges use Orders v2 with vault_id and stored_credential set to merchant-initiated, subsequent usage, so an in-policy order returns completed with a capture id in one call. State is a small JSON store on a Render persistent disk. Retailer fulfillment after payment is simulated and labelled as such; the payment itself is a real PayPal sandbox capture. The agent is not tied to one model: a single file selects the provider and model from environment variables. The demo runs Gemini 3.1 Pro.

Challenges we ran into

  • PayPal's vault experience context rejects vault_instruction together with user_action, which the documentation does not make obvious. We found it by probing the sandbox with four variants.
  • Keeping the spending decision out of the model's hands. The policy engine is plain TypeScript with a full audit trail, so a user can trust the "why" of every decision.
  • The first agent loop would search eight times, find nothing, and end with an empty summary marked "completed". Fixing it meant a search cap, a required terminal decision, an explicit "nothing found" outcome, and a fallback summary, so every run ends in one honest state.
  • Product search is uneven: office supplies are well covered, printer-ink cartridges are not, and some retailers have no offers in the index. The agent has to be comfortable finding nothing.
  • Designing the mandate schema so plain language maps cleanly onto caps, periods, merchants, categories, and an auto-approve threshold without turning into a form.

Accomplishments that we're proud of

  • A real merchant-initiated charge flow driven by an agent, with consent and revocation handled by PayPal rather than by us storing anything sensitive.
  • Decisions that are deterministic, explainable, and visible in the UI next to the agent's reasoning.
  • Frugal by construction: budget-capped search, cheapest-match selection, and pre-search refusal of clearly disallowed categories mean the owner's money is the last thing the agent reaches for. In testing it chose a $34.99 case of paper over five $9.02 reams.
  • All four outcomes verified end to end against the live sandbox: auto-paid, held for approval and then paid on tap, refused by policy, and nothing found.

What we learned

Agentic commerce is a trust problem before it is a shopping problem. Putting the policy in code and the consent in PayPal made the agent feel safe to hand money to. We also learned that an agent needs a way to give up: without an explicit "nothing found" path it will keep searching and then invent a result.

What's next for Errandly

Recurring errands on a schedule, shared mandates for households and small teams, price-drop watching inside an active mandate, and a merchant-side view that shows the mandate behind each charge.

Built With

  • channel3
  • gemini
  • google-ai-studio
  • next.js
  • paypal
  • paypal-agent-toolkit
  • paypal-orders-api
  • paypal-payment-method-tokens
  • paypal-rest-api
  • paypal-vault
  • react
  • render
  • tailwind
  • typescript
  • vercel-ai-sdk
Share this project:

Updates

Submission history