Inspiration

Agents that buy things for people went from demos to real rails in 2025: PayPal's Agent Toolkit and MCP servers, Perplexity checkout, PayPal's support for Google's AP2, the Agentic Commerce Protocol in ChatGPT, Visa Intelligent Commerce and Mastercard Agent Pay (sources in the README).

What nobody has made easy is the boring, essential part. You tell an agent "restock my coffee, max $30 an order, only these three shops, never a subscription, ask me above $25", and you need to know it can't do anything else. People aren't there yet: in an ACI Worldwide / YouGov survey of UK adults (June 2026), only 43% trusted an agent to stay within a spending cap.

Leash is our answer: the agent can propose anything, but only what you signed can be paid.

What it does

  • Plain words in, signed rules out.
    • You describe the mandate, and a model drafts a typed policy.
    • Code rejects any amount or store you didn't write.
    • Code, not the model, renders the rules back into plain language. You sign that with an Ed25519 key created in your browser.
  • PayPal holds the budget. Funding a mandate creates a PayPal Orders v2 order with intent: AUTHORIZE, approved once. That authorization is the hard ceiling.
  • Every cart is checked, deterministically.
    • About 20 rules: merchant identity (with lookalike detection), price, category, subscriptions, quantity, per-purchase cap, budget, remaining allowance, velocity, split orders, order count, the ask-first line, replay, signature, dates and the kill switch.
    • The outcome is allow, ask or deny, with reasons in plain language. The model never gets a vote.
  • Merchant verification before capture. An allowed cart gets a short-lived, single-use signed receipt. The merchant verifies it (/v1/verify), and then Leash makes a partial capture against the authorization.
  • Human in the loop where it matters.
    • Carts above your ask-first line wait for your signed approval.
    • A hard-rule violation can only be waived as a one-off you approve on PayPal. That is never allowed for spoofed stores, tampered carts or replays.
  • One tap to stop. Revoking a mandate, or the global kill switch, voids the PayPal authorization.
  • Proof.
    • Every purchase has a chained intent receipt (JWS) linking your mandate, the agent's reasoning, the cart, the checks and the PayPal ids.
    • It exports as JSON and PDF, and can be submitted to a PayPal dispute through the Disputes API.
    • Every step is in a hash-chained audit trail.
  • Red team built in. Eight attacks run through the real checkout path, and all are blocked: prompt injection on a product page, a lookalike store, a split purchase, a sneaky subscription, going over the cap, a gift-card cash-out, a tampered price and a replay.
  • Works with other agents. Leash is also an MCP server. It gives any agent shopping tools, never payment tools.

How we built it

  • Backend: Python, FastAPI, Pydantic and SQLite.
    • A deterministic policy engine, an Ed25519/JWS module (cryptography) and a hash-chained ledger.
    • A PayPal REST client with OAuth caching, PayPal-Request-Id on every write, retries under the same id, and webhook verification.
  • PayPal (sandbox):
    • Orders v2: create with AUTHORIZE, get and authorize.
    • Payments v2: capture an authorization with final_capture: false, void, get an authorization and refund.
    • Disputes v1: list, get and provide evidence with a PDF.
    • Webhook signature verification and OAuth.
    • Demo carts follow the PayPalCart shape from PayPal's agentic commerce Cart API.
  • AI: Nebius Token Factory (OpenAI-compatible).
    • Qwen/Qwen3-30B-A3B-Instruct-2507 compiles mandates and runs the shopping agent.
    • google/gemma-3-27b-it drafts dispute statements.
    • Every model step has a deterministic fallback, and no model output reaches a money path.
  • Frontend: React 18, TypeScript, Tailwind v4, Motion and Lenis, with WebCrypto Ed25519 for signing on the device.
  • Testing:
    • 55 offline pytest tests, with at least one per threat in THREAT_MODEL.md. They also run the real REST client against a mock PayPal transport.
    • A labelled fixture simulator mirrors PayPal's documented responses, so the whole product runs without keys.

AI tools used

Tool Where How it is used
Nebius Token Factory, Qwen/Qwen3-30B-A3B-Instruct-2507 Runtime Turns a plain-language mandate into a JSON policy draft, which code then grounds and validates. Also writes the agent's search query and picks a product with a short rationale.
Nebius Token Factory, google/gemma-3-27b-it Runtime Drafts a factual dispute statement from signed receipt facts. If the draft doesn't state the real amount and merchant, a template is used instead.
Claude Code (Anthropic) Development A coding assistant used while building and testing. It is not part of the running product.

About the demo video

  • PayPal in the video is Leash's fixture mode. It is labelled on screen throughout, and the AI model is real.
  • Why not the real sandbox:
    • Our PayPal developer account is in India, so both of its default sandbox test accounts are India-registered.
    • PayPal refuses a payment between two Indian accounts ("This seller doesn't accept payments in your currency").
    • So no sandbox buyer could approve the allowance while we recorded.
  • What does run on the real sandbox: sandbox mode is in the repo. In our sandbox runs, Leash created real Orders v2 AUTHORIZE orders and reached PayPal's buyer approval page.
  • To try sandbox mode yourself: add your REST app keys to .env (see KEYS_NEEDED.md), and the PayPal step becomes the real sandbox approval page.

Challenges we ran into

  • Keeping the model away from the money without making it useless.
    • The answer was a strict split: the model drafts and explains, while code grounds every number and store, renders the plain language and makes every decision.
    • We found and fixed a subtle failure: the model read "ask me above $50" as a $50 per-order cap. The compiler now refuses to reuse a number the text already gave another meaning.
  • PayPal is more lenient than a mandate. PayPal accepts captures of up to 115% of an authorization (or +$75), so Leash checks the remaining allowance itself before every capture.
  • Authorization lifetime. Authorizations last up to 29 days, with a 3-day honor period. That shaped mandates into 28-day allowances that renew.
  • Testing payments without keys.
    • We built a fixture simulator that reproduces PayPal's documented shapes and labels itself everywhere.
    • It also reproduces the rules our safety tests depend on: approval before authorization, partial captures, voids after a partial capture, duplicate invoice_id and request-id replay.

Accomplishments that we're proud of

  • All eight red-team attacks are blocked through the same path a real agent uses, each with a plain reason.
  • Revoking a mandate releases the funds at PayPal itself, not just in our database.
  • Receipts can be verified offline by a merchant with a public key, and they export as dispute evidence.

What we learned

Agentic commerce safety is mostly unglamorous engineering:

  • identity by id, not by name;
  • idempotency keys;
  • single-use nonces;
  • signatures over hashes;
  • and a clear line between what a model may suggest and what code decides.

What's next for Leash

  • Passkey-backed signing and real accounts.
  • Per-merchant authorizations, or PayPal vaulting for merchants that integrate directly.
  • Publishing the receipt format and the verify endpoint as a small open spec.
  • Mapping mandates onto AP2's open and closed mandates.

Try it

  1. Run pip install -r requirements.txt, then uvicorn leash.app:app --port 8000, and open http://localhost:8000/app.
    • No keys are needed: PayPal runs in a labelled fixture mode, and agents use offline rules.
  2. Walk through the demo:
    1. New mandate → Coffee restock → Compile → Sign.
    2. Approve allowance on PayPal → Approve (simulated).
    3. Restock my usual… → open the receipt.
    4. Red team → Run all eight.
    5. The power button (kill switch).
  3. Run every test offline with pip install -r requirements-dev.txt && pytest.

Code (MIT): https://github.com/Thanatos9404/leash

Built With

  • cryptography
  • ed25519
  • fastapi
  • gemma
  • mcp
  • motion
  • nebius-token-factory
  • paypal-disputes
  • paypal-orders-v2
  • paypal-payments-v2
  • paypal-webhooks
  • pydantic
  • python
  • qwen
  • react
  • sqlite
  • tailwindcss
  • typescript
Share this project:

Updates

Submission history