Stellar Agent Merchant Lab

Independent Stellar testnet merchant for reproducible agent purchase validation.

Merchant Lab is the seller-side counterpart to Stellar Agent Spend Hub. An agent discovers resources through MCP, receives a machine-readable quote, requests a purchase URL, handles an MPP 402 Payment Required challenge, and receives a resource plus a privacy-safe merchant receipt.

The local mode is explicitly simulated. It never emits a transaction hash or claims settlement. Real testnet settlement activates only with official Stellar MPP configuration, a separate merchant account, and atomic Upstash storage.

Why a separate project

A buyer paying a seller in another repository, process, deployment, and Stellar account proves more than an application calling itself. Merchant Lab creates that independent trust boundary and doubles as a reusable Provider Kit acceptance harness.

flowchart LR
  Agent["AI agent"] --> MCP["Merchant MCP quote"]
  MCP --> URL["Purchase URL"]
  URL --> Challenge["MPP 402"]
  Challenge --> Hub["Spend Hub policy"]
  Hub --> Human["Human confirmation"]
  Human --> Merchant["Merchant USDC account"]
  Merchant --> Delivery["Resource and receipt"]

Current capabilities

• Three machine-purchasable resources priced from 0.001 to 0.01 USDC.
• Provider definition at /.well-known/agent-provider.json.
• MCP stdio and stateless Streamable HTTP transports.
• Official Stellar MPP Charge integration for testnet USDC.
• Local 402 -> credential -> delivery -> receipt simulation.
• One-time local credentials and replay rejection.
• Eight adversarial scenarios for buyer-policy tests.
• Sanitized merchant receipts with no PII, secrets, XDR, or fake hashes.
• Stateless checksummed simulated receipts that survive Vercel cold starts.
• Independent buyer script and ten automated tests.
• Zero known npm vulnerabilities.

Quick start

npm install
npm run qa
npm run build
npm run dev

Open http://localhost:4180.

In another terminal:

npm run demo:buyer -- --resource=market-signal --yes

Without --yes, the buyer stops at the human-confirmation boundary.

Public interfaces

Interface	Purpose
GET /.well-known/agent-provider.json	Machine-readable provider definition
GET /api/catalog	Resource catalog and purchase URLs
GET /.well-known/legal-context.json	LCP terms and verifiable ATR hash
GET /api/resource/:id	MPP-protected delivery
GET /api/scenarios	Valid and adversarial buyer tests
GET /api/receipts/:id	Sanitized merchant evidence
GET /api/health	Public readiness without secrets
POST /mcp	Stateless MCP Streamable HTTP
npm run mcp:serve	Local MCP stdio server

MCP tools

• list_resources
• quote_resource
• list_test_scenarios
• get_merchant_receipt

There is no MCP payment-execution tool. The MCP server quotes resources; Spend Hub owns policy and confirmation.

Test scenarios

• happy
• over-budget
• wrong-recipient
• wrong-asset
• wrong-network
• expired
• unavailable
• delivery-failure

Only happy is executable. Adversarial scenarios generate non-chargeable challenges or failures for buyer validation.

Real Stellar testnet mode

Configure private Vercel environment variables:

• MERCHANT_SIMULATION_ENABLED=false
• MPP_ENABLED=true
• MPP_STELLAR_RECIPIENT=<merchant G address>
• MPP_SECRET_KEY=<32+ random characters>
• UPSTASH_REDIS_REST_URL
• UPSTASH_REDIS_REST_TOKEN

Server-side public configuration:

• PUBLIC_BASE_URL
• MPP_NETWORK=stellar:testnet
• MPP_PRICE_USDC=0.01
• STELLAR_HORIZON_URL
• SOROBAN_RPC_URL

No buyer secret belongs in this project or Vercel deployment.

Acceptance gate

Real evidence requires:

1. A distinct merchant testnet account and USDC trustline.
2. Official MPP challenge for the quoted resource.
3. Spend Hub buyer validates price, recipient, asset and network.
4. Human confirmation occurs before signing.
5. Merchant receives USDC and delivers the resource.
6. Merchant and buyer receipts reference the same public hash.
7. Replay produces no second debit.
8. Pending/simulated evidence never contains a hash.

See architecture, threat model, and deployment runbook.