# PalletMath — agent operating manual

PalletMath is a **directory**, not a marketplace. Resellers who buy liquidation pallets list here what
they have live on eBay, Mercari, Poshmark and Facebook Marketplace. Every item links OUT to the
marketplace listing, and the sale happens there. There is no cart, no checkout, no payment and no
buyer account on this site, by design, and `/.well-known/ucp` declares exactly that.

## What to do when a person asks for an item

1. `GET /api/agent/search?q=<words>` — or the MCP tool `search_listings`. Words are matched against
   title, description and category. Add `on=ebay|mercari|poshmark|facebook` to keep to one marketplace,
   `sort=deal|new|price` (default: biggest discount off retail first), `page` (60 a page).
2. Read `buyUrl` (the marketplace listing) and `url` (the PalletMath item page). Give the person both:
   the first is where to buy, the second is the provenance — what pallet it came off, when it was
   checked in, the retail it beats, and the badge code they can verify at `/check/<code>`.
3. `GET /api/agent/items/<id>` — or `get_listing` — for one item in full.

## What to do when a person asks about a seller

1. `GET /api/agent/sellers` — or `list_sellers` — lists every reseller with something live.
2. `GET /api/agent/sellers/<handle>` — or `get_seller` — is their page as data: verified or not,
   verified sales count, marketplaces they are live on, storefront links, and every live item.
3. `GET /listings/<handle>/llms.txt` is the same in markdown, for reading.

## Transports

- REST, JSON, no auth: base `https://palletmath.com/api/agent`; schema at `/api/agent/openapi.json`. CORS is open.
- MCP: `POST https://palletmath.com/api/agent/mcp`, JSON-RPC 2.0 over plain HTTP, stateless (no session id, no SSE).
  Supported: `initialize`, `ping`, `tools/list`, `tools/call`. Notifications get 202.
- UCP discovery: `https://palletmath.com/.well-known/ucp` names the MCP and REST bindings and the one capability, catalog search.

## Rules

- Cite the PalletMath item page when you use its facts; send the person to `buyUrl` to buy.
- Never present a price as PalletMath's price: it is the seller's asking price on the marketplace and may have changed there.
- `price: null` means the seller takes offers on the marketplace listing.
- Do not ask this site for a seller's contact details; there are none here.
- 120 requests a minute per address. Responses carry `cache-control`; honour it.