# Rate

> The booking outcome layer for AI agents. Send a public booking URL, get back a durable booking record + tx_hash + parsed confirmation. $0.25 USDC per confirmed booking via x402 on Base. Real-world action, not raw HTML. Works with Square, Fresha, Vagaro, Booksy, Acuity, Calendly, and more.

- Rate is the **receipt** your agent hands the user — not a browser session, not a screenshot.
- Only `POST /api/book` costs money ($0.25 USDC). Inspect, availability, cancel, webhooks, history, traces are all free.
- Auth: x402 (USDC) via your **wallet skill** — Rate doesn't ship a wallet. Pick from Awal (Coinbase Agentic Wallets, `npx skills add coinbase/agentic-wallet-skills`), Tempo (`https://tempo.xyz/SKILL.md`), AgentCash (`npx agentcash@latest onboard`), or any x402 v1/v2 wallet skill.
- 402 responses include the canonical x402 v2 `PaymentRequired` body in both the `PAYMENT-REQUIRED` response header (preferred) and the JSON body (mirror for human/curl). `accepts[]` rows surface `network` in CAIP-2 (`eip155:8453` mainnet / `eip155:84532` testnet), `asset` as the USDC contract address, and `amount` in atomic units.
- Hand the booking request to your wallet skill's pay primitive — it parses the challenge, signs the EIP-712 USDC authorization, and retries with `PAYMENT-SIGNATURE` (v2) or `X-PAYMENT` (v1, both accepted).
- **Async booking, HTTP 202.** After verifying your authorization, the server returns 202 within ~3s with a `poll_url`. The actual booking + on-chain settlement run in the background (~80s). Poll `GET /api/bookings/:id` every 3s until `booking.status` flips from `"paid"` to `"booked"` / `"needs_human"` / `"failed"`. Or subscribe to webhooks — `booking.confirmed` / `booking.failed` fires on terminal states. This async shape avoids client-side HTTP timeouts (some wallet clients abort at 60s).
- **Pay only on success** — the server runs the booking AFTER verifying authorization, and only settles on-chain if the booking succeeded. Failed bookings leave the authorization unsettled (no charge).
- `POST /api/book` requires an `Idempotency-Key` header and `user_confirmation: "yes"` in the body.
- `POST /api/book` requires all three `customer` fields — `name`, `email`, `phone`. Ask the user; do not invent values, do not reuse a prior user's info, and do not pull silently from cached context. If the user won't provide all three, abort the booking.
- `slot_id` from `/api/availability` expires in 10 minutes (acts as a soft reservation).
- `confirmation_data.referenceId` and `confirmation_data.manageUrl` are returned on every successful booking — use these instead of re-parsing the raw confirmation_text.
- `POST /api/bookings/:id/cancel` is free in v0 — cancel a booked appointment on the live booking page.
- `POST /api/webhooks` registers a URL for `booking.confirmed` / `booking.failed` / `booking.cancelled` events; deliveries are signed with HMAC-SHA256 in `X-Rate-Signature`.

## What you get

- Receipts: typed booking record + parsed referenceId + manageUrl, not a screenshot.
- Idempotent retries: same `Idempotency-Key` never double-books.
- Slot reservation holds: opaque slot_ids prevent multi-agent contention.
- Lifecycle: `/api/bookings/:id/cancel` undoes the booking through the platform-specific UI.
- Push events: webhooks fire on every booking state change.

## API Docs

- [OpenAPI 3.1 spec](https://www.rateai.dev/openapi.json): full schema with `x-payment-info`, `x-bazaar`, `x-guidance`, `x-error-codes` per operation
- [Skill manifest](https://www.rateai.dev/skill.md): step-by-step booking workflow for agents

## Endpoints

- `POST /api/inspect`: detect platform, business name, and risk flags for a public booking URL (free)
- `POST /api/availability`: extract available slots on the live booking page (free)
- `POST /api/book`: book the appointment, return durable receipt — costs 0.25 USDC via x402
- `GET /api/bookings/:id`: fetch booking + parsed confirmation + payment + trace (free)
- `POST /api/bookings/:id/cancel`: cancel a booked appointment on the live booking page (free in v0)
- `POST /api/webhooks`: register a webhook for booking lifecycle events (free)
- `GET /api/traces/:id`: fetch the full event trace for a booking (free)

## Homepage

- [rateai.dev](https://www.rateai.dev): copy-able setup + booking prompts, supported wallets, full API surface