proxy-shopping: buy anywhere with crypto through a proxy shopper MCP server

proxy-shopping-web

Buy from cash-only shops with crypto, or earn as a proxy shopper: the browser app, guided demo, TypeScript protocol library and MCP server of proxy-shopping, a P2P network where a local shopper buys for remote users who pay through a 2-of-3 escrow with timelocks. Agents: MCP server io.github.pad01g/proxy-shopping (packages/mcp), skills npx skills add pad01g/proxy-shopping-go, AGENTS.md; overview for machines: https://pad01g.github.io/proxy-shopping-docs/llms.txt.

Documentation in 14 languages: https://pad01g.github.io/proxy-shopping-docs/

Browser side of proxy-shopping (spec: ../proxy-shopping-go/docs/spec.md, lab: docs/lab.md there).

packages/core   @proxy-shopping/core — protocol library (TypeScript, ESM, browsers and Node 22)
apps/web        React + Vite single-page app for every role (Japanese UI)
apps/demo       the lab's integrated demo page: every role with its own key in one browser, a guide per scenario
scripts/        docker helpers for integration and browser tests

Host tools are not required; everything runs in docker.

# install, build, unit tests
docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm npm ci
docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm npm run build
docker run --rm -v "$PWD":/src -v "$PWD/../proxy-shopping-go":/proxy-shopping-go:ro -v ps-npm:/root/.npm -w /src node:22-bookworm npm test

# integration: bitcoind signet + anvil (lab contracts) + nostr-rs-relay
scripts/integration.sh
# the built web app in Chromium against a mini lab (TS shopper, faucet, escrow …)
scripts/e2e-web.sh
# the demo in mock mode (GitHub Pages build) in Chromium: every scenario, nothing leaves the page
scripts/e2e-demo-mock.sh

# web image (config.json is mounted at runtime)
docker build -f apps/web/Dockerfile -t proxy-shopping-web .
docker run -p 8080:80 -v $PWD/config.json:/usr/share/nginx/html/config.json:ro proxy-shopping-web

Mounting ../proxy-shopping-go read-only lets the unit tests check docs/test-vectors.json and lab/keys/public.json. Without the vectors file npm test fails, so CI cannot pass silently; set SKIP_VECTORS=1 to run the other tests without it.

apps/demo

Try it in your browser: https://pad01g.github.io/proxy-shopping-web/ (everything simulated in the page). That build runs in mock mode (?mock=1, header switch モック / Mock): the relays, the BTC chain (with script checks), a real EVM with the lab's Safe and escrow-module bytecode, the faucet, the rates, the shops and the shopper-1 node run inside the browser (a SharedWorker shared by all windows), while the four roles use core's real clients. Details, what is simulated and its limits: apps/demo/README.md. The mock e2e (all scenarios, English, separate windows, no request leaving the page): scripts/e2e-demo-mock.sh; Pages is deployed by .github/workflows/pages-demo.yaml.

Shortened. The full README is on GitHub.