ShopAgent

Let AI Do the Shopping for You

Copy this prompt into Claude, ChatGPT, or your favorite AI assistant.

I want to shop online using ShopAgent. Connect to the ShopAgent MCP server at https://api-production-8d20.up.railway.app/api/mcp and help me find the best products across all stores. Search catalogs, show me images and prices, check for discounts, and help me pick the best deals.

API Endpoints

Every ShopAgent store exposes these endpoints. Paid endpoints use HTTP 402 micropayments — no subscriptions, no upfront API keys.

Search Products

POST$0.01 / search

Full-text search across a store’s product catalog. Returns matching products with variants, images, and pricing.

POST /apps/shopagent/api/products/search

Get Product Details

GET$0.001 / lookup

Fetch full details for a product by its handle. Includes all variants, availability, and pricing.

GET /apps/shopagent/api/products/:handle

Create Cart

POSTFree

Add items to a cart. Returns a cart ID for use in checkout.

POST /apps/shopagent/api/cart

Start Checkout

POST$0.25 / checkout

Convert a cart to a checkout session with buyer info and shipping address.

POST /apps/shopagent/api/checkout

Complete Checkout

POST1% commission

Finalize the checkout with a payment token. Creates a Shopify order on the merchant’s store.

POST /apps/shopagent/api/checkout/:id/complete

Discovery

ShopAgent stores broadcast capabilities via well-known URLs. Your agent discovers stores without prior configuration — like search engines discover robots.txt.

# Discover a store's capabilities curl https://store.myshopify.com/apps/shopagent/shopagent.json # Read LLM-friendly shopping instructions curl https://store.myshopify.com/apps/shopagent/llms.txt # Browse the global directory curl https://api-production-8d20.up.railway.app/api/directory

Authentication

Transactional endpoints require a Bearer token. Stores provide an API key on plugin install. Discovery endpoints are public.

Authorization: Bearer sk_agent_xxxxxxxxxxxxx

HTTP 402 Payment Flow

Paid endpoints return 402 on first request with payment requirements. Pay via Tempo USDC or Stripe SPT, then retry with the credential.

# Step 1: Request → 402 POST /api/products/search → 402 { "payment_requirements": { "amount": "0.01", "currency": "USD", "method": "tempo" } } # Step 2: Pay (handled by agent payment SDK) # Step 3: Retry with credential POST /api/products/search Authorization: Payment <credential> → 200 { "products": [...] }

MCP Server

For agents supporting the Model Context Protocol, a full MCP server exposes shopping tools directly. Any MCP-compatible agent can connect and shop all stores on the network.

Endpoint: https://api-production-8d20.up.railway.app/api/mcp Tools: list_stores Discover all stores on the network search_products Search a store's catalog get_product_details Full product info by ID create_checkout Start a checkout session pay_with_spt Pay with Shared Payment Token get_checkout_status Check checkout state

Connect Your Agent

To connect an AI agent to the ShopAgent network, add this MCP server configuration. Once connected, the agent can discover and shop any store on the network automatically.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{ "mcpServers": { "shopagent": { "command": "npx", "args": ["-y", "mcp-remote", "https://api-production-8d20.up.railway.app/api/mcp"] } } }

Claude Code

Add to your project's .mcp.json:

{ "mcpServers": { "shopagent": { "type": "url", "url": "https://api-production-8d20.up.railway.app/api/mcp" } } }

Any MCP Client

Point your MCP client at:

https://api-production-8d20.up.railway.app/api/mcp

Or ask your AI agent: "Connect to the ShopAgent MCP server at https://api-production-8d20.up.railway.app/api/mcp so I can shop online."

Pricing

Endpoint	Cost	Method
Product Search	$0.01	HTTP 402
Product Detail	$0.001	HTTP 402
Create Cart	Free	—
Update Cart	Free	—
Start Checkout	$0.25	HTTP 402
Complete Checkout	1%	Commission

Documentation