# Milk Market - Full Description for LLMs

> Milk Market is a permissionless, Bitcoin-native marketplace for local food and decentralized food systems, built on the Nostr protocol. It connects local food producers directly with buyers. Raw milk and dairy are one example among many: meat, eggs, produce, baked goods, honey, and other handmade local goods are all welcome. There is no central gatekeeper; listings live on Nostr relays, and the platform adds caching, search, storefronts, payments, and an AI-agent interface on top.

## What Milk Market is

Milk Market is an open marketplace for local and decentralized food systems. Anyone can become a producer without asking permission. Sellers publish product listings as Nostr events (kind 30402); buyers browse them on the website or through AI agents. The platform is designed to be censorship-resistant: because data lives on Nostr relays, no single company can remove a producer from the network.

Raw milk and dairy were the founding use case, but the marketplace is for local food broadly: meat, eggs, fresh produce, baked goods, honey, preserves, and handmade goods.

## How buying works

- Buyers can check out as a guest (just an email) or with their own Nostr keys.
- Supported payments: Bitcoin over the Lightning Network, Cashu ecash, cards (Stripe or Square), and manual fiat methods (Venmo, Cash App, Zelle, etc.).
- Milk Market charges no platform fee on sales. Bitcoin payments have no fees at all, and if a seller accepts cards through Stripe or Square, that processor charges its own standard processing fee.
- Carts can mix payment methods and currencies. Free-shipping thresholds and payment-method discounts are supported.
- On card (Stripe) checkouts, sales tax is automatically calculated from the buyer's shipping address and shown at checkout when the seller has turned it on.
- Orders are delivered as encrypted Nostr messages (NIP-17 gift wraps) to the seller, plus optional email confirmations.

## How selling works

Producers follow a guided onboarding (see the Producer Guide):

1. Create an account with a Nostr identity (new or existing).
2. Choose a membership: a free plan with unlimited listings, Herd ($21/month or $168/year, saving 33%) which includes a 30-day free trial for new sellers, or Wrangler (one-time $2,100) for lifetime access to every Herd feature, plus the option to self-host a private, single-tenant copy of your store on your own server.
3. List a product with title, description, price, images, categories, shipping, pickup, variants, and bulk pricing.
4. Manage orders and communicate with buyers through encrypted chat.
5. (Herd) Customize a storefront at /stall/[slug]: colors, fonts, a page builder, SEO/OG meta, and a self-serve custom domain.
6. (Herd) Automate email flows (welcome series, order follow-ups, and re-engagement) with open, click, and conversion analytics for every flow and one-time send, viewable in the orders dashboard or via the MCP get_email_analytics tool. Herd sellers can send these flow emails and order confirmations from their own authenticated email domain; if the domain is not verified, sending automatically falls back to the platform's verified sender so messages always go out. Analytics are private to each seller: every request is scoped to the seller's own account, so no seller can see another seller's analytics, and the platform does not access or use an individual seller's raw email analytics (the platform runs its own storefront as an ordinary seller account with no special access).
7. (Herd) Buy shipping labels through Shippo: connect your own Shippo account (Shippo bills you directly), then quote live rates, buy labels, and issue return labels from the orders dashboard.
8. (Herd) Connect AI agents through the Model Context Protocol (MCP) so autonomous agents can manage listings and orders.
9. Grow your business: update listings, build relationships, share the producer's story, and expand reach.

Sellers who connect a Stripe account can also turn on automatic US sales tax (free, not part of Herd): once enabled with their registered states, Stripe calculates tax from the buyer's shipping address and collects it at checkout on card orders.

## Technology

- Frontend: Next.js (Pages Router), React, TypeScript, HeroUI, Tailwind, PWA.
- Backend: Next.js API routes with PostgreSQL caching for server-side rendering, search, and analytics.
- Protocol: Nostr for events, Blossom for media, NIP-05 for DNS-based identity verification. Implements 15+ NIPs.
- Payments: Lightning, Cashu mints, Stripe Connect, Square, manual fiat.

## For AI agents

Milk Market exposes a Model Context Protocol (MCP) server so AI agents can participate as buyers and sellers.

- Endpoint: POST https://milk.market/api/mcp (JSON-RPC 2.0, Streamable HTTP transport).
- Authentication: bearer API keys prefixed with `sk_`, with three permission levels (read, read_write, full_access).
- Read tools: search_products, get_product_details, list_companies, get_company_details, get_reviews, check_discount_code, get_payment_methods.
- Purchase tools: create_order, get_order_status, list_orders, verify_payment.
- Write tools (full_access): manage profiles, listings, reviews, community posts, messages, relays, media uploads, discount codes, and Cashu wallet operations.
- Paid endpoints follow the L402 standard: a Lightning create_order responds with HTTP 402 and a `WWW-Authenticate: L402` challenge (macaroon + bolt11 invoice). See /.well-known/l402.json (facilitator-agnostic).
- Universal Commerce Protocol (UCP): for agents that prefer plain REST over MCP's JSON-RPC, Milk Market also speaks UCP (the commerce standard backed by Google and Shopify), layered over the same catalog and order pipeline as MCP so the two never drift. Discovery at /.well-known/ucp advertises two capabilities: a catalog (GET /api/ucp/catalog/search with filters + pagination, and GET /api/ucp/catalog/lookup for a single product with live inventory; no key needed) and checkout (POST /api/ucp/checkout/sessions creates a session that places a Milk Market order, GET /api/ucp/checkout/sessions/{id} tracks its status; a read_write `sk_` API key is required). JSON Schemas for the product and checkout-session shapes are at /api/ucp/schemas/product.json and /api/ucp/schemas/checkout-session.json, and /openapi.json documents every endpoint.
- Discovery: /.well-known/mcp.json (JSON-RPC), /.well-known/ucp (Universal Commerce Protocol), /.well-known/agent-card.json (Google A2A), /.well-known/l402.json (L402 payments), /.well-known/agent.json (legacy open-agents schema), /openapi.json (OpenAPI), /agents.txt (policies), /skill.md (agent skill).

Custom seller storefronts (a seller's own domain or /stall/<slug>) serve the same tailored treatment: agents requesting markdown/JSON/plain-text get shop-specific content, and each storefront exposes its own /llms.txt, /robots.txt, and /rss.xml.

Agents that send `Accept: text/markdown`, `Accept: application/json`, or identify as a known LLM crawler receive non-HTML representations of key content pages.

## Links

- Website: https://milk.market
- Marketplace: https://milk.market/marketplace
- Producer Guide: https://milk.market/producer-guide
- About: https://milk.market/about
- FAQ: https://milk.market/faq
- Contact: https://milk.market/contact
- Source code: https://github.com/shopstr-eng/milk-market
- Nostr: https://njump.me/milkmarket