Tollbooth
by kyungmin-cho
README.md
> Hackathon prototype, no longer maintained. Write-up: [kyungmin-cho/contests](https://github.com/kyungmin-cho/contests/tree/main/2026-11_paypal-tollbooth)
<img src="public/tollbooth-mark.svg" alt="Tollbooth" width="96" />
# Tollbooth
**Your AI agent pays per tool call from one PayPal hold. Approve USD 5, pay USD 0.90 for what it used, and the rest is released.**
You approve one PayPal authorization, which holds the money without charging it. You ask a question, and a Workers AI planner chooses which paid MCP tools to call: for the coffee example, a USD 0.20 demand lookup and two USD 0.35 landed-cost estimates for Korea and Japan. Calls above USD 0.30 wait for your OK, and a retry returns the stored result at USD 0.00. When you finish, PayPal captures what was used, once. If nothing was used, the authorization is voided.
**[Judge guide](https://tollbooth.arcsolve.workers.dev/judge) · Video: <!-- YouTube URL after upload -->**
Music: BombinSound / Pixabay
The video is a recording of this code on local `wrangler dev` against PayPal sandbox on October 30, 2026 (capture `9FY331048G298983K` for USD 0.90 and one voided zero-use authorization). On October 19 the deployed build, which still used a fixed research task, captured `2RA569713M861961N` for USD 0.90, voided `2FC89859D10835132`, and verified six PayPal-signed webhooks before applying them. 192 Vitest tests and 15 Playwright tests.
## How PayPal and AI fit together
1. **PayPal Orders v2, `intent: AUTHORIZE`.** You approve the session limit in your PayPal wallet.
2. **Workers AI (`@cf/zai-org/glm-4.7-flash`)** reads your question and the tool catalog and chooses the calls. Tollbooth checks the plan against the catalog, the argument schemas, a six-call cap and your remaining limit, and never rewrites it. It never holds a payment credential.
3. **Policy and consent.** A deterministic policy checks price, merchant and budget, and you decide anything above the threshold. When you close the session, Tollbooth sends a single capture with `final_capture: true` for metered usage, or voids the hold if nothing was used.
4. **Verified webhooks.** Every PayPal event must pass `verify-webhook-signature` before it counts. Pending is not paid.
Tool publishers see each session and charge on a merchant dashboard.
## Try it
Follow [/judge](https://tollbooth.arcsolve.workers.dev/judge). You need a **Personal sandbox buyer** from [PayPal Developer](https://developer.paypal.com/sandbox-testing/accounts/); never enter a production password. Open a USD 5 session, ask the AI to choose tools, approve the limit on PayPal, come back in the same browser, check status, run the plan and finish.
No account? [`/run/rehearsal`](https://tollbooth.arcsolve.workers.dev/run/rehearsal) walks through the same screens in your browser. It doesn't call PayPal or the model.
## Connect an MCP client
Use Streamable HTTP at `https://tollbooth.arcsolve.workers.dev/mcp`. Discovery works without credentials. Protocol versions `2026-07-28` and `2025-11-25` are tested.
Open [/connect](https://tollbooth.arcsolve.workers.dev/connect), issue a temporary client credential, and set it as the client's Authorization bearer header. Keep it in the client's secret store, never in prompts or source. Paid calls go through the [Tollbooth adapter](src/client/adapter.ts) with its policy and consent callbacks, and carry `sessionId`, `callKey`, `maxPriceCents` and `pricingVersion` under `params._meta.tollbooth`. `tollbooth_open`, `tollbooth_status` and `tollbooth_close` manage the session. A payment-required result is not permission to pay. The [contract tests](tests/contract/mcp.test.ts) show both protocol versions.
## Run locally
Node 26.10 and pnpm 12.5.1; dependency versions are locked.
```sh
pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm db:local
pnpm dev
# http://127.0.0.1:8787
pnpm test:browser
pnpm verify:secrets
```
The rehearsal needs no PayPal keys. Financial tests use synthetic provider responses in real Workers, DO and D1 runtimes. For local sandbox sessions, create an ignored `.dev.vars` with `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_MERCHANT_ID` and an independently generated `OWNER_TOKEN_SIGNING_KEY` (32+ characters), chmod 0600. Merchant access needs `MERCHANT_ADMIN_TOKEN` and `MERCHANT_COOKIE_SIGNING_KEY`; webhooks need a registered `PAYPAL_WEBHOOK_ID`. The local config has no AI binding, so the planner shows its fallback unless you add `"ai": { "binding": "AI", "remote": true }` and log in with `wrangler login`. Never use `VITE_*` for secrets. See [sandbox instructions](docs/M5.md#sandbox-driver) and [webhook setup](docs/M2-M3.md#webhook-registration). Playwright uses port 8790 with synthetic provider and model fixtures and creates no real orders; set `TB_EVIDENCE` to keep its screenshots.
## Architecture and money safety
```text
Buyer / AI host → policy + human consent → Agents SDK createMcpHandler
→ SQLite Session Durable Object
→ PayPal Orders v2 AUTHORIZE → capture / void
↓ verified webhooks
Session DO → durable outbox → D1 projections → merchant dashboard
```
One Cloudflare Worker serves the Vite/React assets and stateless MCP. Each session has a SQLite Durable Object; D1 handles admission, recovery anchors and projections. UI: Tailwind, shadcn Base UI and AG Grid Community.
- Integer cents and server-owned prices; budget is reserved before a call runs.
- One usage entry per successful call key; a replay adds no charge.
- Closing stops new reservations and waits for in-flight work.
- One settlement per session: a positive amount with `final_capture:true`, or a void for zero use.
- Unknown provider outcomes are reconciled against existing IDs, never answered with a new capture.
- Durable alarms, the outbox and recovery scans keep working after the browser closes. D1 never authorizes spending.
## Deployment (operator only)
The checked-in remote config targets Worker `tollbooth` and D1 `tollbooth-m1`; it is not a deploy target for judges. Operators confirm `pnpm exec wrangler whoami`, build, apply D1 migrations with `pnpm exec wrangler d1 migrations apply tollbooth-m1 --remote --config wrangler.remote.jsonc`, set secrets with `wrangler secret put <NAME> --config wrangler.remote.jsonc`, and deploy with `pnpm exec wrangler deploy --config wrangler.remote.jsonc`. Another installation needs its own account, resources, origin and AI binding.
## Limits
Sandbox only, USD, one merchant, and tool data from fixed tables. The planner can only use the two tools in the catalog. Daily AI and session quotas can limit judging. Details: [evidence and limits](docs/HARDENING.md), [address move](docs/ADDRESS.md).
[Design](docs/DESIGN.md) · [UI](docs/UI.md) · [Plan](docs/PLAN.md) · [MIT license](LICENSE) · [Third-party notices](THIRD_PARTY.md)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data