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

io.github.pad01gPublished by GitHub account pad01gv0.1.2Updated Oct 24, 2026

Buy at cash-only or unsupported shops with BTC via a proxy shopper and 2-of-3 escrow, or earn as one

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Lets an assistant buy from cash-only or unsupported shops through a proxy shopper using BTC held in 2-of-3 escrow, and manage those orders.

What you can do
  • Inspect the network, relays, coordinators and trusted shopper/escrow combinations, and check the wallet identity, address and balance
  • Find offers for a shop URL, region and payment, request a quote and review its validation, then accept it
  • Track orders: status, timeline, next steps, cancel before funding, and report a shopper or escrow
  • Move money with explicit confirmation: fund escrow, confirm receipt, open a dispute, co-sign a ruling or refund, reclaim after the timelock
  • Back up the wallet mnemonic, and get plans and registry files for earning as a proxy shopper
When to use it
Useful when you want an agent to arrange a purchase at a shop that does not accept your payment method, with escrow and dispute handling, or when you are evaluating running a proxy shopper node. Not for ordinary card checkout or mainstream retail.
Requirements
Runs locally over stdio, normally as a Docker image with a volume mounted at /data for the key and orders (Node 22 also works without Docker). Optional environment variables: PS_NETWORK (ps-main or lab), PS_DATA_DIR, PS_LAB_URL, PS_CONFIG_URL, PS_COORDINATORS. Network access to Nostr relays and a BTC signet chain service.
Before you install
Several tools move money and require confirm: true: fund_order, confirm_receipt, open_dispute, countersign_ruling, accept_refund_offer, refund_after_timelock. export_backup reveals the 12-word mnemonic. The data directory holds the key controlling every open order's escrow, so keep and back it up. Opening a dispute hands the escrow the key to your address. The public network is new, may have no trusted shoppers, and pays in signet BTC with no market value; USDC is unavailable there.

Installation

In SourceWeft

  1. Open proxy-shopping: buy anywhere with crypto through a proxy shopper in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

proxy-shopping MCP server

An MCP server that lets an AI agent use the proxy-shopping P2P network as tools:

  • Buy from cash-only or unsupported shops with crypto through a proxy shopper, with a 2-of-3 escrow. You pay BTC into a per-order escrow (you, the shopper, an escrow); the shopper buys and ships; you release the payment when the items arrive. If something goes wrong the escrow rules a split, and after the T2 timelock you can take everything back alone.
  • Earn as a proxy shopper. A precise plan for running the always-online shopper node, and the registry entry for getting listed.

It runs next to the agent (stdio) as one participant with its own key. Protocol logic is @proxy-shopping/core, the same code the web app runs. The session stays up while the server runs, so quotes, shipping updates and rulings keep arriving and are stored in the data directory. Registry name: io.github.pad01g/proxy-shopping.

The public network ps-main is new. There may be no trusted shoppers yet (network_info says how many shopper × escrow combinations are trusted). Payments there are BTC on signet, a test network whose coins have no market value. USDC is not available on ps-main yet.

Run

Claude Code:

sh
claude mcp add proxy-shopping -- docker run -i --rm -v proxy-shopping-mcp:/data ghcr.io/pad01g/proxy-shopping-mcp:0.1.2

Other clients (mcp.json):

json
{  "mcpServers": {    "proxy-shopping": {      "command": "docker",      "args": ["run", "-i", "--rm", "-v", "proxy-shopping-mcp:/data", "ghcr.io/pad01g/proxy-shopping-mcp:0.1.2"]    }  }}

The volume at /data holds the key and the orders. Keep it: without it you lose the key that controls the escrow of every open order (back it up with export_backup). One data dir = one identity; use a separate volume per agent or per person.

The local docker compose lab (proxy-shopping-go, demo server on http://localhost:8888):

sh
claude mcp add proxy-shopping-lab -- docker run -i --rm --add-host=host.docker.internal:host-gateway \  -v proxy-shopping-mcp-lab:/data -e PS_NETWORK=lab -e PS_LAB_URL=http://host.docker.internal:8888 \  ghcr.io/pad01g/proxy-shopping-mcp:0.1.2

MCPB bundle (Claude Desktop and other MCPB clients: open the file to install; needs Node 22+): proxy-shopping-<version>.mcpb from the releases; build it with node packages/mcp/scripts/build-mcpb.mjs after npm run build -w @proxy-shopping/core. Agents installing the server: llms-install.md.

Without Docker (Node 22, from the repository root): npm ci && npm run build -w @proxy-shopping/core -w @proxy-shopping/mcp, then node packages/mcp/dist/server.js (bin proxy-shopping-mcp).

VariableDefaultMeaning
PS_NETWORKps-mainps-main: public Nostr relays (relay.damus.io, nos.lol, relay.primal.net), BTC signet via mempool.space, coordinators and signed trust events from the registry. lab: the compose lab through its demo server
PS_DATA_DIR~/.proxy-shopping-mcp (image: /data)the mnemonic (mnemonic, mode 0600, created on first run) and the state per network (state-<network>.json)
PS_LAB_URLhttp://localhost:8888lab only: the demo server (relays at /relay-1 /relay-2, /esplora, /evm, /faucet, /rates, /deployments/31337.json)
PS_CONFIG_URL / PS_CONFIG_FILEunseta web-app config.json (format of proxy-shopping-go/lab/web-config.json: relays, coordinators, esplora, evm_rpc, deployments_url, rates, timelock_policy, …) that overrides the preset
PS_COORDINATORSunsetcomma-separated coordinator pubkeys that replace the preset's trust roots

Tools

ToolWhat it does
network_infonetwork, relays, coordinators, chains, how many shopper × escrow combinations are trusted, an honest status
walletidentity pubkey, BTC signet address and balance (EVM/USDC where the network has it)
lab_faucetlab only: test BTC / USDC to this wallet, mine blocks
find_offerstrusted shopper × escrow combinations for a shop URL, region and payment, with fees, cash regions and provenance (coordinator → operator list)
request_quoteorder from one combination and wait for the quote; returns its validation: rate deviation from our own sources, the recomputed escrow address, the timelocks
get_order / list_ordersstatus, timeline and next steps; get_order can wait for a status
accept_quoteaccept a valid quote (a strong rate deviation needs acknowledge_rate_deviation)
fund_ordermoves money: pay the lock and the escrow upfront fee (confirm: true)
confirm_receiptmoves money: items received, sign the payout to the shopper (confirm: true)
open_disputeask the escrow to decide; hands it the evidence and the key to your address (confirm: true)
review_ruling / countersign_rulingcheck the escrow's split, then co-sign it (moves money, confirm: true)
accept_refund_offermoves money: co-sign the shopper's cooperative refund (confirm: true)
refund_after_timelockmoves money: after T2, take the funds back alone (confirm: true)
cancel_ordercancel before funding
reportreport the shopper or escrow to the operator that listed them
export_backupshow the 12-word mnemonic (confirm: true)
become_shopperthe plan for earning as a proxy shopper: requirements, fees, node config and compose file for ps-main, how to get listed
registry_entrythe exact file for a pull request to the registry, in its format: shoppers/<name>.json {pk, contact, description, regions (cash regions), payments, escrows}, escrows/<name>.json {pk, contact, description, sla_days}, operators/<name>.json {pk, contact, description, regions}, coordinators/<name>.json {pk, contact, description, url?, bundle?}

A purchase: network_info → wallet (fund it) → find_offers → request_quote → accept_quote → fund_order → (get_order until delivered) → confirm_receipt.

Every tool answers with a short text plus the same data as structured JSON.

Safety

  • Tools that move money or disclose secrets do nothing without confirm: true; without it they show what would happen (amounts, recipients, fees). An agent should show that to its human and ask before confirming.
  • A quote that fails validation (combination not trusted, escrow address that does not match our own computation, timelocks outside the policy, amounts that do not add up) cannot be accepted. A rate more than 10 % away from our own sources needs an explicit acknowledgement.
  • Payouts are signed only for the template the protocol allows (release to the shopper, a refund to you, a ruling that matches its split); completed / settled / refunded are reported only once the chain shows the payment.
  • The mnemonic never leaves the data dir except through export_backup. The delivery address is encrypted for the shopper; the escrow can read it only when you open a dispute.
  • Trust comes only from the coordinators you configure (network_info lists them and where they came from). Orders are only as good as the shoppers and escrows that operators list.

Test

sh
# from the repository root, in Docker (no host Node needed)docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm \  sh -c "npm ci && npm run build -w @proxy-shopping/core && npm test -w @proxy-shopping/mcp"
# end to end against the running compose lab: a BTC order through MCP tool calls over stdiodocker run --rm --add-host=host.docker.internal:host-gateway -v "$PWD":/src -v ps-npm:/root/.npm -w /src/packages/mcp \  -e PS_LAB_URL=http://host.docker.internal:8888 node:22-bookworm npm run test:lab

The unit tests drive every tool through an MCP client against core's in-memory world (relays, chain, a scripted shopper and an escrow), and run the registry's own validator (proxy-shopping-registry/scripts/registry.ts validate) on the files registry_entry writes; they expect ../proxy-shopping-registry next to this repository (or PS_REGISTRY_DIR, or mounted at /proxy-shopping-registry; SKIP_REGISTRY=1 skips it). Add -v "$PWD/../proxy-shopping-registry":/proxy-shopping-registry:ro to the Docker command above.

Source: packages/mcp/README.md at commit 0185c47

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.1.2LatestSep 30, 2026
  2. v0.1.1Sep 30, 2026
  3. v0.1.0Sep 29, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts