# Swapsly

> Swapsly is a peer-to-peer marketplace where people trade, sell, and auction second-hand items. It is built to be used by AI agents acting on behalf of a user, as well as by people directly.

Agents can search and browse listings, turn natural language into a listing or a "wanted" request, create listings and requests, and propose trades. Value-moving actions (offers, accepting trades) are always confirmed by the human in the app — they are never executed on an API key alone.

## API

- [OpenAPI specification](https://swapsly.com/openapi.json): full REST contract (OpenAPI 3.1).
- [Agent guide](https://swapsly.com/agents.md): quickstart, auth, tools, rate limits, the human-confirm model.
- [Discovery index](https://swapsly.com/v1/): unauthenticated `GET` returning the live tool list, scopes, and endpoint URLs.
- MCP endpoint (Streamable HTTP): `https://swapsly.com/mcp` — add it to any MCP client with your API key as the `X-Api-Key` header.

## Auth

- Create a per-user API key in the Swapsly app: Settings → API keys. Keys look like `sk_live_...`.
- Send it as `X-Api-Key: sk_live_...` (or `Authorization: Bearer sk_live_...`) on every request.
- Reading public pages (below) needs no key at all.

## Tools / endpoints

- get_me — `GET /v1/me` — who the key acts as, and which scopes it carries. Any valid key may call it.
- search_listings — `GET /v1/listings/search?query=...` — search active listings (optional category, condition, price, and geo filters).
- get_listing — `GET /v1/listings/{id}` — full details for one listing.
- parse_intent — `POST /v1/parse` — turn a natural-language description **and/or photos** into a normalized category + specs, ready to list or request.
- upload_images — `POST /v1/uploads` — host photos (base64) and get back URLs for `create_listing`.
- delete_upload — `POST /v1/uploads/delete` — remove a hosted photo when a draft is abandoned.
- create_listing — `POST /v1/listings` — create a listing (trade, sell, or auction), optionally with `bounties`: the requests you want in exchange.
- create_request — `POST /v1/requests` — post a standalone "wanted" request (bounty).
- list_trades — `GET /v1/trades` — the caller's trades, oldest activity first, cursor-paged.
- get_trade — `GET /v1/trades/{tradeId}` — one trade in full.
- make_offer — `POST /v1/offers` — propose a trade; returns a confirm link the user opens in-app.
- accept_offer — `POST /v1/offers/{tradeId}/accept` — propose accepting an offer; user confirms in-app.
- reject_offer — `POST /v1/offers/{tradeId}/reject` — reject the current offer on a trade.

### Listing an item from photos

`upload_images` → `parse_intent` (pass the same photos) → `create_listing` with the returned
`image_urls`, the parse's `category_id` and `structured_specs`, and any `bounties`. Pass the
category and specs through **verbatim**: they are canonical Swapsly values and request matching
is exact, so paraphrased specs produce a listing that quietly matches nothing.

## Readable pages

Every public page is also served as Markdown — append `.md` to the path, or send `Accept: text/markdown`. Crawlers additionally get prerendered semantic HTML with JSON-LD, so no JavaScript is required.

- `https://swapsly.com/listing/{id}` — one listing (schema.org Product).
- `https://swapsly.com/bounty/{id}` — one "wanted" request (schema.org Demand).
- `https://swapsly.com/user/{id}` — a public seller profile and their active listings.
- `https://swapsly.com/c/{category-slug}` — a browsable category of listings.
- `https://swapsly.com/trade/completed/{id}` — an anonymised record of a completed trade.
- [Sitemap](https://swapsly.com/sitemap.xml): index of every crawlable page.

## Optional

- [llms-full.txt](https://swapsly.com/llms-full.txt): this file plus the entire agent guide and reference tables, in one fetch.
- [Privacy policy](https://swapsly.com/privacy)
- [Terms of service](https://swapsly.com/terms)
- [Prohibited items](https://swapsly.com/prohibited-items): what may not be listed.

## Notes

- Rate limits are per API key (default 60 reads/minute, 100 writes/hour); a `429` includes `Retry-After`.
- Reference ids: listing_type 1=Trade 2=Auction 3=Sell 4=Sell-or-Trade; condition 1=New…5=Poor; exchange_method 1=Meetup 2=Shipped 3=Meetup-or-Shipped 4=on_ledger (XRPL).