For Stores: Setup Guide

This guide walks you through making your storefront Nash-ready — so any AI shopper (Claude, ChatGPT, custom agents) can discover your products and close a deal at your prices, and so hesitant human shoppers on your site get a brand-voiced agent that converts them.

End state: a running nash.v1 backend serving your catalog, your discovery files, and a live seller agent. Setup takes about 30 minutes for a developer.

For the underlying wire format see PROTOCOL.md. For the big picture see OVERVIEW.md.

1. Install

pip install pier39-merchant-server

This gives you the pier39-merchant CLI and the pier39_merchant_server library. It bundles the seller agent, the discovery-file generation, and the per-IP rate limiting — you only bring a catalog.

2. Write your `catalog.json`

The catalog has two parts: a store block (who you are, your rep's voice, your default policy) and a products array. Each product carries public fields that shoppers see and hidden fields that only the seller agent uses.

{
  "store": {
    "name": "Vintage Supply Co",
    "city": "San Francisco",
    "rep_name": "Nash",                    // the seller agent's name in chat
    "rep_title": "Floor Manager",
    "tagline": "Curated mid-century pieces",
    "headline": "Design classics, honestly priced",
    "about": "Family-run since 2009. We authenticate every piece.",
    "policy_default": "Free returns within 30 days.",
    "category_label": "Furniture"
  },
  "products": [
    {
      "id": "eames-lounge-01",              // stable, URL-safe, unique
      "kind": "product",
      "name": "Eames Lounge Chair",
      "subtitle": "Herman Miller, walnut",
      "description": "Original 1970s production, refinished shell…",
      "year_made": "1972",
      "condition": "Excellent, minor patina",
      "list_price": 4200,                    // what the shopper sees (integer, USD)

      // ---- HIDDEN merchant state (never served to shoppers) ----
      "floor": 3600,                         // hard walk-away; agent never goes below
      "levers": [                            // concessions, cheapest first
        "Free white-glove delivery in the Bay Area",
        "Include the matching ottoman at cost",
        "5% off for pickup this week"
      ],
      "inventory_note": "Only one in stock; slow mover, OK to move on price."
    }
  ]
}

Field reference

Store (all public): name, city, rep_name, rep_title, tagline, headline, about, policy_default, category_label.

Product — public: id, kind, name, subtitle, description, year_made, condition, list_price.

Product — hidden (stripped from /negotiate.json and /api/store/catalog): floor, levers, inventory_note.

Guidance on the hidden fields — these are what turn a static page into a negotiator:

floor is your true walk-away. The agent is guaranteed never to quote below it. Set it where you'd genuinely rather lose the sale.
levers are non-price (or low-cost) concessions, listed cheapest first. The agent trades them in a decreasing-concession pattern instead of just dropping price — bundled items, delivery, warranty, timing.
inventory_note is free-text context (aging stock, last unit, high margin) that tunes how eager the agent is to close.

3. Run the server

pier39-merchant serve catalog.json --host 0.0.0.0 --port 8000

That single command stands up a complete nash.v1 backend. It serves:

Path	What
`/negotiate.json` + `/.well-known/negotiate.json`	Protocol descriptor
`/api/store/catalog`	Public catalog (hidden fields stripped)
`/api/store/chat/start?product_id=…`	Open a negotiation session
`/api/store/chat/{sid}/say?message=…`	Send a message
`/api/store/chat/{sid}`	Read history
`/llms.txt`, `/robots.txt`, `/sitemap.xml`	Crawler + agent discovery
`/badge.svg`, `/badge-dark.svg`	Embeddable Nash-compliance badge

The seller agent needs an LLM key in the environment (e.g. ANTHROPIC_API_KEY) to generate replies. See pier39-merchant serve --help for the full flag list, including the per-hour session rate limit.

4. Point your domain at it

Put the server behind your domain (or a subdomain like shop.yourbrand.com) via your normal reverse proxy / TLS setup, or deploy it to any host that gives you HTTPS. Two checks confirm you're live:

curl https://yourbrand.com/negotiate.json | jq .negotiate_protocol   # → "nash.v1"
curl "https://yourbrand.com/api/store/chat/start?product_id=eames-lounge-01"

The second call should return a session_id, a greeting, and a next URL.

5. Get discovered

Two ways AI shoppers find you:

The Nash Directory. Submit your store to the public registry so every shopper agent using the Nash MCP can find you by brand, category, or product. (Open a PR against the directory repo linked from OVERVIEW.md, or use the hosted onboarding flow.)
On-page signals. Your /negotiate.json, /llms.txt, and /sitemap.xml let agents that land on your domain self-discover the protocol. Drop the compliance badge (/badge.svg) on your storefront to advertise support.

6. Test against a shopper

The fastest end-to-end test is to shop your own store from Claude:

Add the Nash MCP connector in Claude Desktop (Settings → Connectors → Add custom connector → https://mcp.pier39.ai/mcp).
Ask: "Find and negotiate the Eames Lounge for me."

You'll watch the shopper agent discover your descriptor, open a session, and negotiate against your floor and levers — exactly what a real AI shopper does.

Checklist

[ ] catalog.json written, every product has a floor and levers
[ ] /negotiate.json returns negotiate_protocol: "nash.v1"
[ ] A start-chat call returns a session_id + next
[ ] Hidden fields absent from /negotiate.json and /api/store/catalog
[ ] HTTPS + domain wired
[ ] Listed in the Nash Directory and/or badge on-site