# OpenStall Collective

> Handmade goods from home makers who sell over WhatsApp, pooled into one collective supplier for AI shopping agents that buy in bulk.

Agents can search the makers' live listings, and read each listing in full and each maker's trust card. Agents can also order: request_quote asks each matching maker's seller agent for an offer, negotiated within limits she set and checked in code, and plain code splits the order across makers, cheapest first. create_collective_order turns that plan into a draft order, which a person approves on OpenStall before PayPal holds any money. Seeded makers and their numbers are made-up demo data, marked data_source "seeded_demo" wherever they appear.

## MCP storefront

- MCP server: https://openstall-collective-api.onrender.com/mcp (Streamable HTTP, no sign-in)

Its tools (none of them spends money):

- search_products(query, max_price, ship_to, deadline, quantity): Search handmade products from OpenStall's makers. It never spends money and changes no order.
- get_product(product_id): One live listing in full. It only reads: it never spends money and changes no order.
- get_trust_card(seller_id): A maker's trust passport. It only reads: it never spends money and changes no order.
- request_quote(items, quantity, max_unit_price, deadline, ship_to): Ask OpenStall's makers for a quote. It spends no money: it stores the request and asks each maker's agent.
- create_collective_order(request_id, accept_partial): Turn a quote's plan into one draft collective order. It spends no money.
- checkout(order_id): The link your human opens to approve the order. It spends no money and changes no order.
- get_order_status(order_id): An order's status and each maker's share. It only reads: it never spends money and changes no order.

## How payment works

- The buyer's human approves one PayPal authorization for the whole order. It reserves the money; nothing is taken yet.
- Each maker's share is captured only when she proves she shipped: she sends a photo of her courier receipt (pay-on-proof). A maker who drops out is never paid, and her share is released.
- No MCP tool captures, refunds or moves money.
- Payments here run in PayPal's sandbox: no real money moves.

## Without MCP

- [Catalog](https://openstall-collective-api.onrender.com/catalog.json): every live listing as JSON, with the seller, price, capacity per week, ship days, photos, trust score and data_source. A copy is at most 60 seconds old.
- One listing: `https://openstall-collective-api.onrender.com/catalog/{product_id}.json`, its entry in the catalog, as get_product gives it.
- A maker's trust card: `https://openstall-collective-api.onrender.com/passport/{seller_id}`, her trust passport, as get_trust_card gives it.

## Trust passports

A maker's trust card is her passport: orders delivered, on-time and dispute rates, photo originality, a score from 0 to 1 (0.4 x on time + 0.3 x (1 - disputes) + 0.3 x photo originality), when it was issued, and data_source.

To check a trust card's signature, verify it with Ed25519 over the card's canonical JSON: every field but "signature", keys sorted at every level, no whitespace, UTF-8 text rather than \u escapes, and whole-number floats up to 2**53 written as integers (0.0 as 0, 1.0 as 1), the way JavaScript writes them. The public key is at https://openstall-collective-api.onrender.com/passport/public-key (standard base64 of its 32 raw bytes). Or ask OpenStall: https://openstall-collective-api.onrender.com/passport/{seller_id}/verify checks her stored card, and POST https://openstall-collective-api.onrender.com/passport/verify checks any card you send it: change one number, and it fails.