AgentShelf

Turn WhatsApp product photos into a store any AI shopping agent can find, quote and buy from, with human-approved PayPal checkout. Made by small sellers, found by AI, paid via PayPal.

Comment

Inspiration

Meera makes block-printed scarves in Jaipur. Her whole business lives in WhatsApp: photos, voice notes, "is this still available?", a PayPal link typed by hand. Buyers are starting to shop through AI assistants, and those assistants can't read a WhatsApp thread. They need a catalog they can search, a price they can trust and a checkout they can call.

PayPal's agentic commerce work reaches merchants who already sit on a platform. Sellers like Meera aren't on any platform, so they're about to become invisible. We wanted to give them an agent-ready store without asking them to learn e-commerce.

What it does

For the seller: photos in, store out.

  • The seller sends product photos (WhatsApp or our web Listing Studio). A vision model drafts the title, description, category, attributes and a suggested price.
  • AI never sets the price. The seller confirms price and stock before anything goes live, then edits by text (price 45 #12, stock 0 #12).
  • Every store gets a public page with schema.org product data and its own MCP endpoint.

For the buyer's agent: a store it can actually buy from.

  • Any MCP client can call four tools: search_products, get_quote, create_checkout, get_order_status.
  • get_quote snapshots item price, shipping and an expiry on the server. The model can't invent or change an amount.
  • create_checkout locks stock and the shopper's budget in Postgres, then creates a PayPal Orders v2 order paid straight to that seller.
  • A human always approves the payment on PayPal. Agents find and propose; people pay.

After the sale. Verified PayPal webhooks update the order, the seller gets a WhatsApp alert, and track #A123 DHL 1234567890 pushes tracking to the PayPal order. A seller dashboard built on AG Grid and AG Studio shows products and orders, plus refunds, invoices and a 7-day sales summary.

Try it without installing anything: the Buyer Playground is a chat with an AI shopping agent wired to our real MCP server. Every tool call shows live, under a budget cap.

How we built it

  • Backend: Python, FastAPI and the official MCP Python SDK (stateless Streamable HTTP), so the MCP server scales behind a load balancer. SQLAlchemy 2 and Alembic on PostgreSQL 17.
  • Money is integer minor units end to end. Reservations use SELECT … FOR UPDATE; the job queue uses SKIP LOCKED with LISTEN/NOTIFY wake-ups, retries and dedupe.
  • PayPal (REST, idempotent PayPal-Request-Id): Orders v2 create and capture, webhook signature verification, order tracking, refunds, invoicing, Catalog Products and dispute reads. A circuit breaker isolates PayPal outages.
  • AI: a provider strategy over Gemini and Claude. A strict schema checks every draft, and we screen captions and chat for personal data and prompt injection.
  • Frontend: React 19, TypeScript and Vite, with AG Grid and AG Studio for the seller dashboard.
  • Storage: private Cloudflare R2 for photos, with EXIF stripped first.
  • Quality: 340 backend tests against real Postgres (locking, constraints, migrations) and 16 Playwright browser tests with axe accessibility checks.

Challenges we ran into

  • Gemini 3 tool calling broke on round two. The first real-key run showed that every buyer chat failed after the first search: Gemini 3 requires its thoughtSignature back on each function call. Our provider-neutral history now carries it and strips it before any other model sees it.
  • Reasoning ate the answer. One listing draft spent 1,150 of 1,200 output tokens thinking, so the JSON got cut off. We now set an explicit reasoning level and reserve a separate token allowance. Real drafts take 4.4 s and 10.0 s.
  • Agents and money don't mix by default. We made the server the only source of truth for price, stock, budget and payment status, and kept a human approval step on every payment.
  • Load spikes and failures. We moved to ranked full-text search with indexes, a short read-through cache and an optional read replica. Request deadlines turn a hung database into a fast 503 instead of a hang.

Accomplishments that we're proud of

  • A real end-to-end agent purchase in PayPal sandbox: Gemini made 4 MCP searches and requested a quote in 12.7 s, and after human confirmation the order was created in 3.1 s. Our $40.00 and PayPal's $40.00 match, paid to the right seller.
  • Load: 151 requests/s on product search from a single local worker (p95 2.8 s, 0 errors at 100 concurrent requests).
  • Failover: zero errors across 2,000 requests while one of two web replicas was stopped mid-burst.
  • Accessibility: axe finds zero violations on our phone-width screens.

What we learned

Agentic commerce is mostly a trust problem. The model is great at finding and explaining; it shouldn't own prices or payments. Clear tool contracts plus a human approval step make agent shopping feel safe. Testing against real providers early catches the bugs that mocks hide.

What's next for AgentShelf

  • A pilot with real sellers in India selling to overseas buyers. Live payments are enabled one merchant at a time, after PayPal eligibility checks.
  • More agent surfaces through the same MCP endpoint, and voice-first listing in regional languages.
  • Payouts for sellers who can't receive payments directly, and shipping-label integration.

Built With

Share this project:

Updates

Submission history