# Agent Restaurant Reservation API

> Agent-first API for searching and booking restaurant reservations on Resy. Supports per-user API keys, MPP (Tempo), and x402 (Base) wallet authentication.

- Agents authenticate via per-user API key (`x-agent-key` header) or crypto wallet (MPP / x402)
- API keys available for $5 — purchase at https://agentres.dev/purchase or contact admin
- API key auth carries user identity (no userId parameter needed) and booking is free
- Wallet auth: identity endpoints are free (zero-dollar challenge), booking costs 0.01 USDC
- 402 responses include both MPP and x402 headers — clients choose either protocol

## API Docs

- [OpenAPI 3.1 spec](https://agentres.dev/openapi.json): Full machine-readable API schema with request/response types and `x-payment-info` per endpoint
- [API Reference](https://agentres.dev/api-reference.md): Human-readable endpoint docs with auth details, request/response schemas, and error codes

## Agent Onboarding

- [Onboarding skill](https://agentres.dev/skill.md): Conversational workflow — create account, link Resy, search restaurants, check availability, and book

## Auth Protocols

- [MPP (Tempo)](https://tempo.xyz): Machine Payments Protocol — 402 challenge via `WWW-Authenticate`, wallet signs and retries with `Authorization: Payment <credential>`. Chain: Tempo Mainnet (ID 4217), currency: USDC (`0x20C000000000000000000000b9537d11c60E8b50`), recipient: `0xC295e19eB630E29a4Dd81f7242E6b51B49486d93`
- [x402 (Base)](https://www.x402.org): HTTP 402 standard — 402 response includes `PAYMENT-REQUIRED` header, client signs `PaymentPayload` and retries with `PAYMENT-SIGNATURE` header. Chain: Base (ID 8453), currency: USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`), recipient: `0x2DD94d7CB82cb882E7599f020661A77AdF9fDaF7`

## Endpoints

- `GET /api/search?query=<name>`: Search Resy for any restaurant by name (no auth)
- `POST /api/account`: Create account, links wallet automatically (identity auth)
- `GET /api/me`: Get user profile and Resy link status (identity auth)
- `POST /api/link-resy`: Link Resy account via two-step OTP (identity auth)
- `GET /api/availability?venue_id=<id>&party_size=<n>&day=<YYYY-MM-DD>`: Check available time slots (identity auth)
- `POST /api/book`: Book a reservation, costs 0.01 USDC (paid auth)