# bcshops

> bcshops is a marketplace of independent stores. People buy from the store, not
> from the platform. An agent can shop the catalogue, compare products, fill a
> basket and check out — and, with a seller key, run a store end to end.

Links worth having:

- [Marketplace](https://bcshops.com/) — the shopper-facing catalogue.
- [Start a store](https://bcshops.com/vendor) — open a shop and list products.
- [Agent API & MCP keys](https://bcshops.com/agent-keys) — create a `bcx_` key.
- [MCP server card](https://bcshops.com/.well-known/mcp.json) — the tools and
  transport, machine-readable.
- [Agent discovery manifest](https://bcshops.com/.well-known/ard.json) — this
  marketplace as an agentic resource.
- [Shopper skill](https://github.com/mediafill/bcshops/blob/main/skills/bcshops/SKILL.md)
  — step-by-step instructions for shopping and selling here.

## What a shopper agent can do

- **Search** the marketplace (`GET /v1/search?q=...`) with typo tolerance, facets
  and related searches. Results name the selling store for every product.
- **Compare** products on price, delivery promise and stock by reading
  `GET /v1/products/{slug}` for each candidate.
- **Fill a basket** (`POST /v1/cart/items`) and **check out** (`POST /v1/checkout`)
  with a cart token, an email and a shipping address. Checkout reserves stock
  and credits first, then takes payment; a saved payment can be resumed or
  cancelled by the shopper.
- **Track and manage** an order (`GET /v1/orders/{orderNumber}`), request a
  return (`POST /v1/returns`) and follow its status.
- **Earn credits**: one credit per dollar on every order, redeemable as one
  dollar per 100 credits. Guest shoppers claim credits by verifying their email.

## What a seller agent can do

- Run a store from a design brief or a product CSV (`POST /v1/agent/seller/setup`).
- Manage listings, variants, offers, prices, stock and photos.
- Fulfil orders, buy carrier labels, and review returns.
- Read the numbers: revenue, a contribution estimate that separates item
  revenue, discounts, recorded costs, refunds, platform fees, processing fees
  and lost disputes, plus the reconciliation that ties them to the total.

## How to call it

- **MCP** (recommended): `https://bcshops.com/mcp`, Streamable HTTP, key in the
  `Authorization: Bearer` header.
- **REST**: `https://bcshops.com/v1/...`. The public catalogue needs no key;
  `/v1/agent/*` and `/v1/me/*` need one.

## Keys

A person signs in at `https://bcshops.com/agent-keys` and creates a key with a
**daily** and a **monthly** spend limit. The key looks like `bcx_...`. When the
cap is reached the key stops working rather than quietly continuing.

## Agent surface

- MCP server card: `/.well-known/ard.json`
- Skill: `skills/bcshops/SKILL.md` (`application/agent-skills+md`)

## Notes for agents

- Prices, discounts and totals are always quoted in cents and include tax and
  delivery. A quote id changes when the cart, prices or availability change.
- A code that does not apply is refused rather than silently dropped.
- Money never moves without confirmation: refunds need provider confirmation,
  and a disputed payment blocks further refunds until it is resolved.