Autonomous Shopping Agent

A web app where you describe a product and a budget, and a CrewAI-orchestrated agent crew finds it via Browserbase/Stagehand, pays Laso Finance's x402 endpoint in USDC (gated by an Ampersend Platform spend limit) for a single-use prepaid card funded for exactly the checkout total, enters that card at checkout, and reports back with a full audit trail.

Phase 0 — research-spike findings (verified 2026-08-17 against live docs/source)

Spike 1: Ampersend onboarding

• Agent skill installed at .agents/skills/ampersend/ via npx skills add edgeandnode/ampersend-sdk#skills/latest (skill v0.0.28, symlinked into Claude Code).
• Python SDK: pip install ampersend-sdk (v0.0.28 on PyPI). Top-level exports: create_ampersend_treasurer, create_ampersend_http_client, AmpersendTreasurer, AmpersendManagementClient, SpendConfig.
• Onboarding path for credentials: install the CLI (npm i -g @ampersend_ai/ampersend-sdk), run ampersend setup start --name "<agent>" → open the returned user_approve_url in your own browser, confirm the verificationCode matches, approve → ampersend setup finish. That yields the smart-account address + agent session key this app needs (AMPERSEND_SMART_ACCOUNT_ADDRESS, AMPERSEND_SESSION_KEY_PRIVATE_KEY). Spend limits (per-tx / daily / monthly) are set during setup start or in the dashboard at https://app.ampersend.ai — payments are co-signed by the Ampersend service, which only signs within those limits, so neither this app nor the agent can bypass them.
• Sandbox: https://api.sandbox.ampersend.ai (Base Sepolia, fund via https://faucet.circle.com/). Production: https://api.ampersend.ai.

Spike 2: paying a plain REST x402 endpoint from Python

Resolved — fully supported standalone, no A2A wrapper and no TypeScript fallback needed. ampersend_sdk.x402.http ships X402HttpTransport, an httpx.AsyncBaseTransport that intercepts any 402, calls treasurer.onPaymentRequired(...) (authorization decision), has the wallet sign, and retries with the payment header. It auto-detects both x402 wire formats:

• v1: requirements in the 402 JSON body, payment in the X-Payment header;
• v2: requirements base64-encoded in the PAYMENT-REQUIRED header, payment in the Payment-Signature header — this is Laso's format.

AmpersendTreasurer.onPaymentRequired asks the Platform API to authorize first (authorize_payment), and returns None on refusal — the transport then hands the original 402 back to the caller, which this app surfaces as TreasurerRefusedError (no silent retry with a smaller amount). NaiveTreasurer + AccountWallet (EOA) cover sandbox plumbing tests and are structurally unreachable in live mode (see Guardrails).

Spike 3: Laso request/response shapes

From https://laso.finance/openapi.json + SKILL.md:

• GET /get-card?amount=<usd> — amount $5–$1000 (decimals allowed; only the sibling /order-intl-card requires whole dollars). x402-paid on Base (eip155:8453) or Solana USDC; fees are added on top of the amount. First 402: body {}, challenge base64 in the PAYMENT-REQUIRED header (accepts array). Second 402 after paying: settlement failure, body {"success": false, "errorReason": ...} — nothing charged, safe to retry. Success response: {auth: {id_token, refresh_token}, user_id, card: {card_id, usd_amount, status: "pending"}} — no PAN/CVV here, and it includes fresh auth so no separate SIWX /auth round-trip is needed after a paid call.
• GET /get-card-data?card_id=... (Bearer id_token) — poll every 2–3 s, ~7–10 s until status: "ready", then card_details: {card_number, exp_month, exp_year, cvv, available_balance}. POST /auth {grant_type: "refresh_token"} renews the token.
• There is no Laso sandbox — every successful /get-card spends real mainnet USDC. Hence the LIVE_MODE gate and the built-in fake client for dry runs.

Stagehand/CrewAI version note

Current CrewAI docs say pip install stagehand — but crewai-tools' StagehandTool is built against the 0.x Python SDK (pinned stagehand<=0.5.9 here). The stagehand 3.x package on PyPI is a different, generated API client and is not compatible. Stagehand 0.5.9 config: StagehandConfig(env="BROWSERBASE", api_key, project_id, model_api_key, model_name="claude-3-7-sonnet-latest", browserbase_session_id=...).

Architecture

Web UI (frontend/) ── FastAPI (backend/main.py) ── Orchestrator (backend/orchestrator.py)
        │                                                │
        │   search ▼                     approve ▼                    checkout ▼
   Shopper Crew (CrewAI +          Payments module (plain        Checkout Crew (CrewAI +
   official StagehandTool)         code, NOT an agent):          custom Stagehand tools):
   finds product, reads exact      AmpersendTreasurer x402 →     fills card via vault
   checkout total, NO payment      Laso /get-card → CardVault    handle, submits, confirms

Two deliberate design choices:

1. The payments step is plain application code, not a CrewAI agent (backend/payments/). Once the human approves a checkout total, "pay $X for a card" is deterministic. A prompt injection on a shopping page can't talk an LLM into a bigger payment because no LLM sits between the approval and the money.
2. Card digits never enter an LLM context. /get-card-data is read server-side and the PAN/CVV go straight into CardVault (in-memory, short TTL). The Checkout Crew gets an opaque handle; CardFillTool resolves it server-side, locates the form fields with observe() (the LLM only ever sees field descriptions), and replays the selectors as pre-observed fill actions — Stagehand executes those directly with no model inference on the values. Tool output is masked (•••• •••• •••• 1234), and a root-logger redaction filter masks any 13–19-digit run in every log line as a backstop.

Guardrails (implemented, tested)

| Guardrail | Where | Test | |---|---|---| | Spend cap lives in the Ampersend Platform, treasurer refusal surfaces as a hard stop (no silent smaller retry) | AmpersendTreasurer + laso_client._raise_for_402 | test_over_limit_payment_rejected_by_treasurer_without_touching_laso | | NaiveTreasurer unreachable when real spending is possible | ampersend_client.assert_treasurer_safe + config.validate_startup | test_naive_treasurer_unreachable_* | | Production Laso never called without LIVE_MODE=true | LasoClient.get_card guard + FakeLasoClient in dry runs | test_dry_run_refuses_production_laso | | Human approval before any USDC moves, approved amount must equal quoted total | Orchestrator._require_approval | test_no_approval_no_funding | | App-level hard ceiling independent of Platform limit | create_task + fund_card | test_budget_hard_ceiling, test_funding_respects_hard_ceiling | | Idempotency: restart never buys a second card | fund_card(existing_card=...) + persisted card_id | test_funding_idempotent_after_crash | | No PAN/CVV in logs/traces | vault-only storage, masked tool output, log redaction filter | test_full_funding_flow_into_vault_no_pan_in_logs, test_secret_repr_never_leaks_pan | | Bounded browser loops | per-session action budget + crew wall-clock timeout | BrowserSession._spend_action, asyncio.wait_for | | Audit trail | data/audit.jsonl, one event per step, streamed over SSE | test_full_sandbox_run_end_to_end |

Setup

uv sync                      # Python 3.12 venv + all deps
cp .env.example .env         # fill in keys (see below)
uv run uvicorn backend.main:app --reload
# open http://127.0.0.1:8000

Keys you need:

1. Browserbase: BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, plus STAGEHAND_MODEL_API_KEY (Anthropic, OpenAI, or Google/Gemini) for Stagehand's own act/extract/observe. For Gemini free tier set STAGEHAND_MODEL_NAME=gemini-3.6-flash and GOOGLE_API_KEY or GEMINI_API_KEY (or pass the key via STAGEHAND_MODEL_API_KEY).
2. CrewAI LLM: ANTHROPIC_API_KEY by default, or set CREW_LLM_MODEL to another LiteLLM model (e.g. gemini/gemini-3.6-flash with GEMINI_API_KEY from Google AI Studio).
3. Ampersend (for sandbox plumbing and live): run the CLI setup flow from Spike 1 and set spending limits in the dashboard before going live.
4. Laso needs no signup — auth is wallet-based and the first paid call creates the account.

Modes

| Mode | ENVIRONMENT | LIVE_MODE | Card issuance | Money | |---|---|---|---|---| | Dry run (default) | sandbox | false | FakeLasoClient stub | none | | Sandbox plumbing | sandbox | false + LASO_BASE_URL → local x402 stub | real x402 loop, NaiveTreasurer or sandbox AmpersendTreasurer | testnet | | Live | live | true | real Laso /get-card | real USDC |

First live run: keep the purchase ≤$10, watch it happen, then grep the logs: grep -rE '[0-9]{13,19}' data/ *.log must return nothing.

uv run pytest                          # 24 tests, no network, no browser, no LLM
uv run pytest tests/test_e2e_smoke.py  # live smoke test — only with LIVE_MODE gates armed

Repo map

backend/
  main.py                 FastAPI app, SSE progress stream, static frontend
  orchestrator.py         search → approval gate → fund → checkout state machine
  config.py               env config + fail-loud startup validation
  store.py                task persistence (tasks.json) + audit trail (audit.jsonl)
  crews/shopper_crew.py   CrewAI agent: find product, read checkout total, never pay
  crews/checkout_crew.py  CrewAI agent: fill card by handle, submit once, confirm
  payments/ampersend_client.py  treasurer selection + x402 httpx client (the money gate)
  payments/laso_client.py       /get-card, /get-card-data, 402 semantics, dry-run guard
  payments/card_vault.py        short-TTL in-memory PAN store, handle-based
  payments/funding.py           deterministic fund step, idempotent on card_id
  tools/browser.py        shared Stagehand session (thread-bridged, action-budgeted)
  tools/card_fill_tool.py CrewAI tools incl. the no-LLM card fill
frontend/index.html       form → approval screen → live progress → confirmation
tests/                    guardrail + flow tests (see table above)

Acceptance criteria status

• [x] Over-limit request rejected by the treasurer itself, Laso untouched (unit-tested with a Platform-refusal double; repeat against the real sandbox Platform once your agent is registered: set a $1 limit and run the smoke test with a $5 card)
• [x] Full sandbox run end-to-end with stubbed card issuance (test_full_sandbox_run_end_to_end)
• [ ] Single live ≤$10 purchase with a fresh Laso card — requires funded keys + a human watching; run the UI with ENVIRONMENT=live LIVE_MODE=true
• [x] No raw PAN/CVV in logs/traces/prompts (tested; re-grep after the live run)
• [x] Kill/restart does not issue a second card (test_funding_idempotent_after_crash)
• [x] Approval screen before any USDC moves, no code path skips it (_require_approval is on the only path into fund_card)