Inspiration

AI assistants can already find products and check out for people. PayPal's agentic commerce services (Agent Ready, Store Sync) cover that buying side. Returns are the other half: in 2025 US retailers expected $849.9B in returns, 19.3% of online sales coming back, and 9% of returns fraudulent (NRF & Happy Returns, Oct 2025). When a buyer's agent asks for a refund, or is talked into "refund me $500", a small cross-border merchant still has to read the message, look up the PayPal capture, decide and click refund. The person reading the message is also the person moving the money. We wanted a returns layer where an agent can ask, but only the merchant can approve.

What it does

TradeOS is a returns inbox for small cross-border physical-goods merchants.

  • Customer messages (any language) and buyer-agent requests land in one queue.
  • A language model (openai/gpt-oss-20b on Groq) turns the words into a strict intent schema. It never sets amounts, eligibility or approvals.
  • Deterministic Python policy checks PayPal's own capture data: status, amount, currency, return window, product.
  • A Safety Gate holds dangerous-product reports (burns, fire, injury) for human safety review before any refund or supplier task.
  • Returns and size exchanges take different paths: a refund, or a (mock) supplier replacement with no money moved.
  • A refund requested by a buyer agent always waits for the merchant, even if the merchant turns on auto-approval. Auto-approval is an experimental opt-in for ordinary customer requests under an amount limit; it is off on the hosted demo.
  • After approval, TradeOS calls the PayPal Sandbox Refund API. Success is shown only when PayPal reports COMPLETED; a signed PayPal webhook and an independent GET confirm it, all on a tamper-evident SHA-256 audit chain.
  • Buyer agents connect over TradeOS's own restricted /mcp gateway (not the official PayPal MCP): place a Sandbox demo order, request a return or exchange, read status, and (with Channel3) find a real product. There is no approve tool and no refund tool.

How we built it

  • PayPal (Sandbox): Orders v2 (create + capture with a Sandbox test card), Payments v2 GET capture and refund, POST .../captures/{id}/refund with an idempotent PayPal-Request-Id, note_to_payer, negative-testing headers for the failure demo, self-verified signed webhooks (PAYMENT.CAPTURE.REFUNDED / REFUND.PENDING / REFUND.FAILED), webhook registration, and read-only Disputes.
  • AI: Groq openai/gpt-oss-20b behind an OpenAI-compatible adapter, strict JSON schema, pydantic validation; anything off-schema becomes UNKNOWN and the policy rejects it. A keyword fallback keeps the demo running if the model is down. The model also translates the code-written customer note, under a guard that keeps every number.
  • Rules: pure-Python policy engine and Safety Gate; a hard guard refuses any refund unless the audit chain holds policy ELIGIBLE and a chained approval.
  • App: FastAPI + Jinja2 server-rendered dashboard, SQLite, AG Grid Community returns inbox, MCP gateway, Channel3 product search for agents, hosted on Render.
  • Quality: GitHub Actions CI with ruff, mypy, pip-audit and a 90% coverage gate (1,845 tests, ~95% coverage, mock PayPal), plus scripts/sandbox_verify.py run by hand against the hosted Sandbox demo.

Measured evidence (hosted build 88b0be9, 9 Nov 2026, real PayPal Sandbox)

Check Result
Hosted sandbox_verify 31/31
Live-model AI end-to-end 11/11
Signed refund webhooks 3/3 verified
Independent PayPal GET reconciliation 3/3 match
Audit chains 10/10 intact
UI behaviour checks over HTTP 10/10
Malformed Origin/Referer 58/58 → HTTP 403
Deterministic policy matrix 582/582 (rules, not LLM calls)
LLM intent eval (52 author-written messages, one run) exact 41/52 vs keyword 17/52

Sandbox refund IDs from that run: 84R36954519561114, 1LF75336ME8988949, 6TJ28435C8083362L. The video was recorded on 49261e5; 88b0be9 differs only in docs and copy.

Challenges we ran into

  • A malformed Origin/Referer (https://[) crashed the CSRF check with a 500; it now returns 403.
  • A refund call that times out may still have moved money, so an unknown outcome is reconciled with PayPal (GET or webhook) instead of being retried blindly.
  • Keeping the model out of the money: amounts come only from PayPal captures and code.
  • A shared, ephemeral demo needs clear hints: free text creates a new Sandbox order, and order IDs typed into a message are not looked up.

Accomplishments that we're proud of

  • Zero refunds approved by an AI agent: the gateway simply has no tool for it, and tests assert the Refund API is never called on rejected, injected or safety-held cases.
  • Every refund is confirmed three ways (Refund API COMPLETED, signed webhook, independent GET) and recorded on a verifiable audit chain.

What we learned

  • An agent should be able to speak for a buyer without being able to spend for the merchant. That boundary belongs in tools and code, not only in prompts.
  • PayPal's idempotency keys, signed webhooks and GET endpoints are enough to make "did the refund really happen?" a checkable question.

Honest limits

  • PayPal Sandbox only — no live money.
  • Public shared demo with no merchant login: any visitor plays the merchant and can press Approve (Sandbox only). /mcp on the public demo is open so judges can act as a buyer agent. A private profile with an operator token and MCP bearer tokens exists.
  • Single merchant, ephemeral database (resets on restart or deploy). Supplier replies are mocked.
  • Buyer identity is unverified (self-declared agent / on-behalf-of names).
  • Auto-approval is experimental, unit-tested only and off on the demo.
  • The audit chain is tamper-evident, not immutable. Not fraud-proof, not production-ready.

What's next for TradeOS

  • Merchant accounts and roles instead of the shared demo.
  • Real supplier channels and order import from store platforms.
  • A measured merchant task study (protocol in the repo; no results claimed yet).

Built With

Share this project:

Updates

Submission history