x402-tablebook

x402-tablebook

Open-source Resy for the agent economy — a self-hosted restaurant reservation server that AI agents (and humans) can book with x402 micropayments. Availability costs $0.001, a booking is a $0.01 refundable hold, and every payment returns its artifact — reservation, cancel token, refund terms, calendar invite — in the same HTTP response.

Why x402 for this

Restaurant booking APIs today mean platform gatekeepers, API-key onboarding, and no-show risk with nothing at stake. With x402 the transaction is the authentication: any wallet — human or agent — pays $0.001 to see real availability and puts down a $0.01 refundable USDC hold to claim a table, with no account, subscription, or integration contract. The hold gives restaurants skin-in-the-game against no-shows while staying trivially refundable on timely cancellation.

Quickstart

git clone https://github.com/nirholas/x402-tablebook
cd x402-tablebook && npm install

# your floor plan and hours live in config/tables.json — edit to match reality
npm run dev

The server ships with the suite's public receive addresses so it runs out of the box. Set PAY_TO_ADDRESS (Base) and SOLANA_PAY_TO_ADDRESS (Solana) in .env to receive the payments yourself.

Then, in another terminal, run the full agent flow (search → book → cancel):

PRIVATE_KEY=0xFundedBaseSepoliaKey npm run client

Fund the client wallet with testnet USDC at faucet.circle.com. Open http://localhost:4021 for the human checkout demo.

API

Full reference: docs/api.md · openapi.json

How x402 works

Pay in USDC on Base or Solana — your client picks the rail.

1. Client calls a paid route with no payment → server answers 402 Payment Required with an accepts[] array holding both rails: USDC on Base (base-sepolia by default) and USDC on Solana, each with amount, token address, and recipient.
2. Client picks one and signs — EVM: an EIP-3009 transferWithAuthorization; Solana: an SPL transferChecked — then retries with the X-PAYMENT header.
3. The facilitator for that rail verifies and settles on the chosen chain — x402.org's for Base, PayAI's for Solana (each overridable by env; no public facilitator settles both).
4. Server responds 200 with the purchased artifact in the body and a settlement receipt in X-PAYMENT-RESPONSE.

Settlement is deliberately last: the payment only settles when the route returns 2xx, so a booking that can't be honoured never charges the payer.

No API keys, no invoices, no minimums — each request pays for itself. Raw wire-level walkthrough: examples/curl.md.

Real backend / configuration

This server sells real inventory you configure — there are no fixtures and no external API keys:

• config/tables.json — your restaurant, hours, tables, slot/seating durations, refund policy.
• Reservations and the refundable-hold ledger persist to data/*.json (file-based, no database).
• SIGNING_SECRET — set in production; confirmations and cancellations carry an HMAC-SHA256 signature over canonical JSON (dev default is baked in for the demo).
• Refund ledger: holds, refunds, and forfeits are recorded per reservation and returned in-response. Settling refunded USDC back on-chain is the operator's action (or an automation you attach) — the signed ledger entry is the customer's claim.
• Payment addresses: PAY_TO_ADDRESS (Base) and SOLANA_PAY_TO_ADDRESS (Solana). Both default to the suite's public receive addresses so the demo runs unconfigured — the server prints a reminder while the defaults are active.
• Facilitators are per-rail: FACILITATOR_URL (EVM, default x402.org) and SOLANA_FACILITATOR_URL (Solana, default PayAI). No public facilitator settles both chains.
• Mainnet: NETWORK=base + a production EVM FACILITATOR_URL. Solana defaults to mainnet; SOLANA_NETWORK=devnet switches it. Use a dedicated SOLANA_RPC_URL in production.

All variables: .env.example

Human checkout

public/index.html is a Resy-style checkout: search slots, tap one, pay with the drop-in @three-ws/x402-payment-modal (loaded from CDN), download the .ics, cancel with one click. The modal reads the dual-rail 402 and offers Phantom/Solflare/Backpack on Solana or MetaMask on Base automatically. It also brings SIWX wallet re-entry (a wallet that already paid signs back in instead of paying again) and client-side spending caps (per-call / hourly / daily), so returning guests don't re-approve every $0.01.

The Solana browser path needs one small server route — Phantom signs serialized transactions, so the SPL transfer has to be built somewhere. src/checkout.ts mounts the package's own Express adapter at /api/x402-checkout; if the optional peer deps aren't installed, that path degrades and the Base path keeps working.

For AI agents

• skill.md — agent-facing service description (endpoints, prices, schemas, payment details).
• /.well-known/x402 — machine-readable manifest served by the app; indexable by x402scan.com, the x402 Bazaar, and agentic.market. Deploy publicly and submit your base URL to be discovered.
• MCP: wrap the endpoints as Claude tools in ~60 lines — see examples/mcp-tool.md.
• Client: examples/agent-client.ts is the complete pay-search-book-cancel loop via x402-fetch.
• Agent guide: docs/agents.md

Docs

Site: https://nirholas.github.io/x402-tablebook/ · Tutorial · API reference · For agents

Part of the x402 Suite.

Support

Questions, integration help, or a bug report: nichxbt@gmail.com — or open an issue.

License

Apache-2.0

Star History

Support the project

If x402-tablebook saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/x402-tablebook and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors