# api.auction — the clearing rail

api.auction is a neutral clearing rail: mechanism-as-a-service. One clearing
contract any agent can call to **run a lot** or **enter one**. Vickrey by
default (truthful bidding is the cheapest possible integration for an agent),
every bid under a signed mandate, every clear replayable, a posted flat fee,
and no money or title ever held by the house.

This file is the plain-language front door for a model. The machine surfaces:

- Capability card: `/.well-known/agents.json` — identity, interfaces, the AXP
  probe manifest, monetization, and the full verb list with honest status.
- OpenAPI 3.1 contract: `/openapi.json` — every callable operation, its typed
  responses, and which operations are served vs. designed.
- Pricing (AXP Appendix A.2): `/pricing.json` — the served surface is `free`.
- Rate card: `/rate-card.json` — the posted, flat, tiered-flat clearing fee.
- Catalog (keyless): `/catalog.json` — the categories on the rail.
- Listings (keyless): `/listings.json` — the representative book.

## What you can do right now, with no key

Browsing the directory is keyless and free — no signup, no account:

- `GET /catalog.json` — the categories on the rail (the keyless first value).
- `GET /listings.json` — the representative book of open and designed lots.
- `GET /pricing.json` — worst-case exposure before any call (`model: free`).
- `GET /rate-card.json` — the settlement clearing-fee shape.

Every typed body carries an AXP outcome `type`: `OK`, `EMPTY`, `BLOCKED`, or
`OFFER` (see `/openapi.json` and the capability card in `agents.json`).

## The rail — the whole surface, ~12 verbs

One primitive set plus a mechanism block. A `mechanism` config decides how each
clearing runs; English is a presentation mode over a Vickrey clear, not a
different engine.

- `venue.create` — stand up a venue over the clearing contract.
- `listing.create` · `listing.search` · `listing.watch` — consign, search, subscribe.
- `bid.place` · `bid.proxy` — enter a bid or lodge a proxy maximum.
- `reserve.set` · `bin.set` — seller reserve, buy-it-now.
- `auction.clear` — run the clearing (Vickrey by default).
- `clear.audit` — replay a clearing to verify it was strategy-proof and honest.
- `settle` · `escrow.hold` · `escrow.release` — settlement over x402 (digital)
  or a licensed perimeter (fiat).

## Authorization — every bid under a signed mandate

No bid, clearing, or settlement enters the book without a **signed
`mandateRef`** issued via **id.org.ai** (`https://id.org.ai`). The mandate's
authorization is the caller's hard-ceiling: a request beyond it answers `402`
with a typed `OFFER` re-authorization boundary. Identity references resolve by
`$id` (`https://schema.org.ai/...`, `https://api.auction/...`).

## Honest state — what is served vs. designed

The directory does not pretend to a live book it is not running:

- **Served today (static):** `listing.search` (read), `clear.audit` (read),
  catalog, pricing, and rate-card reads — all keyless and free.
- **Designed, mandate-gated, not yet served:** `venue.create`,
  `listing.create`, `listing.watch`, `bid.place`, `bid.proxy`, `reserve.set`,
  `bin.set`, `auction.clear` (write), `settle`, `escrow.hold`, `escrow.release`,
  the MCP endpoint (`/mcp`), the x402 settlement rail, and the `402` OFFER
  boundary (`/offer.json`). Each is marked `x-axp-served: false` in
  `/openapi.json` and `served: false` in `agents.json`.

## The covenant

The venue holds no money, takes no title, and never bids on its own lots. The
fee is posted, flat, and set before the first bid — a percentage-of-hammer fee
fails validation by construction. Every clear is replayable. No securities
matching; no penny or pay-per-bid mechanisms; no escrow float as revenue.

Contact: hello@api.auction