Skip to main content
Glama

Tollbooth 🛣️

Give your API a tollbooth — let AI agents discover it, read it, and pay for it.

Built for the PayPal AI Hackathon 2026.

AI agents are about to consume millions of APIs. Today that flow is broken for machines: no way to discover an API (agent-native catalog), no way to read one (LLM-legible docs), and no way to pay for one (per-call billing with autonomous checkout). Tollbooth is the missing commerce layer:

  1. Publish — a developer pastes an OpenAPI spec. APIMatic transforms it and generates typed TypeScript + Python SDKs plus an LLM-readable context file (llms.txt-style) that agents consume.

  2. Discover — the API is listed in the Tollbooth marketplace, exposed to any AI agent through an MCP server (search, read context, compare pricing).

  3. Pay — the agent buys credit packs through PayPal (Orders API, agent-initiated checkout), and every call is metered and billed by the Tollbooth gateway. The developer withdraws earnings via PayPal Payouts.

No human in the loop. Watch a Claude agent do the whole journey: search → read docs → create a PayPal order → get credits → call the API → get billed per call.


Quickstart (5 minutes)

Prerequisites: Node.js 24+, npm.

git clone <this repo> && cd tollbooth
npm install                 # installs all three workspaces (app, mcp, agent)
cp .env.example app/.env    # optional — works with zero keys (mock mode)

# Terminal 1 — the marketplace + gateway + dashboard
npm run dev                 # → http://localhost:3000

# Terminal 2 — the scripted buyer-agent demo (no AI key needed)
npm run demo                # full autonomous purchase journey

# Terminal 3 (optional) — the LLM-driven autonomous buyer agent
#   works with a Gemini key (free: aistudio.google.com) OR an Anthropic key
cd agent && GEMINI_API_KEY=... npm run start -- "Find a sentiment API and run 3 calls. Budget $5."

Open http://localhost:3000/dev before running the demo — watch revenue, usage, and agent purchases update live.

Verify the MCP surface (no LLM needed):

cd agent && npm run smoke

Using the MCP server in Claude Code

claude mcp add tollbooth -- node --import tsx C:/path/to/tollbooth/mcp/src/index.ts

Then just ask Claude: "Search the Tollbooth marketplace for a sentiment API, buy the smallest credit pack, and score this review: '…'"


Related MCP server: Cralo

Modes

Mode

When

Behavior

Mock (default)

no PayPal credentials set

Orders are simulated locally (instant approve + capture). The whole demo runs with zero keys.

Sandbox

PAYPAL_CLIENT_ID + PAYPAL_CLIENT_SECRET set

Real PayPal sandbox: the agent creates an order, the payer approves via PayPal, capture completes via webhook (PAYMENT.CAPTURE.COMPLETED), credits top up automatically.

Live

PAYPAL_MODE=live + your live app's credentials

Production PayPal (api-m.paypal.com): Orders, Webhooks and Payouts all switch to live endpoints. Defaults to the wallet flow (payer approves via PayPal). Unattended agent-card capture in live is PayPal advanced card processing — enable only with account approval, PAYPAL_LIVE_AGENT_CARD=true and real card details in env (a sandbox test card is never sent to the live API). Use your live app's webhook subscription for PAYPAL_WEBHOOK_ID.

APIMatic likewise degrades gracefully: without APIMATIC_API_KEY, listings use the built-in local context generator; with a key, the APIMatic Transformer normalizes specs and the Codegen API produces downloadable SDKs per listing.

Deploy (Render)

The repo ships a Render blueprint (render.yaml) — the hosted demo is a two-minute setup:

  1. Render dashboard → New → Blueprint → pick this repo.

  2. Leave the prompted secrets blank for a zero-credential mock demo, or paste PayPal sandbox keys (PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PAYEE_EMAIL) for real sandbox payments.

  3. For the tollbooth-docs static service, paste your APIMatic dashboard API key — it generates the developer portal at deploy time.

  4. Done — the app self-seeds the demo listing at boot (ephemeral disk is fine: the SQLite DB is rebuilt on every deploy via app/instrumentation.ts). The docs portal deploys as a static site (never sleeps).

To enable webhook-driven credit top-up on the hosted instance, add a webhook in the PayPal developer dashboard pointing at https://<your-render-url>/api/webhooks/paypal (event PAYMENT.CAPTURE.COMPLETED) and set PAYPAL_WEBHOOK_ID.

Developer portal (APIMatic)

portal/ holds an APIMatic portal project generated from the demo API's OpenAPI spec. One command rebuilds everything — the documentation site, downloadable C#/TypeScript/Python SDKs, llms.txt / llms-full.txt agent docs, and AI context plugins for coding assistants:

npm run portal          # regenerate the static portal → portal/out
npm run portal:serve    # live-preview at http://localhost:23513

It's the developer-facing half of the marketplace story: the same spec a developer pastes into Tollbooth produces both the agent-facing context file (via MCP) and this human/agent-friendly portal with SDKs. Generated output (portal/out/) is gitignored; requires an APIMatic account (apimatic auth login).

Environment variables

See .env.example. Copy it to app/.env (and agent/.env for the LLM agent). Nothing is required for mock mode; add keys to go live:

  • PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID — PayPal sandbox app credentials

  • APIMATIC_API_KEY — live spec transformation + SDK generation

  • ANTHROPIC_API_KEY — the autonomous buyer agent (agent/)

Architecture

 Developer (supply)                          AI agent (demand)
 ───────────────────                         ──────────────────
 OpenAPI spec / Postman URL                  Claude (Anthropic API)
       │                                          │  "find a sentiment API,
       ▼                                          │   run 3 calls, stay under $5"
 APIMatic Transformer (normalize)                ▼
       │                                    Tollbooth MCP server
       ▼                                    ├─ tb_search_apis
 APIMatic Codegen API                       ├─ tb_get_api_context   ← context file (llms.txt)
 ├─ SDK: TypeScript + Python                ├─ tb_create_order      → PayPal Orders API
 └─ Context Plugin: llms.txt                ├─ tb_approve_order     → capture / approve URL
       │                                    ├─ tb_call_api          → Tollbooth gateway
       ▼                                    └─ tb_check_credits
 Tollbooth listing + pricing                      │
 (per-call, metered)                              ▼
                                        Gateway: x-api-key auth → credit check
 Dashboard: revenue, usage,                → proxy to upstream API → meter & bill
 payouts via PayPal Payouts API       PayPal webhook: PAYMENT.CAPTURE.COMPLETED
                                      → auto top-up agent credits

Workspaces:

Path

What

app/

Next.js 16 app — marketplace, developer dashboard, REST API, PayPal integration (Orders + Webhooks + Payouts), metering gateway, bundled demo API

mcp/

Standalone MCP server (stdio) — the agent-facing tool surface

agent/

The buyer agent: scripted demo (npm run demo), MCP smoke test (npm run smoke), and the autonomous Claude agent (npm run start)

portal/

APIMatic developer portal for the demo API — docs, downloadable SDKs (C#/TypeScript/Python), llms.txt, and AI context plugins, all generated from the OpenAPI spec via the APIMatic CLI (npm run portal to rebuild, npm run portal:serve to preview)

How each technology is used

  • PayPal — Orders API with two payment modes: agent-card flow (default in sandbox: the agent pays with its own funded card via payment_source.card — the order creates and captures in one call, fully autonomous, no browser) and PayPal-wallet flow (PAYPAL_AGENT_CARD=false: human approves via the PayPal checkout URL, capture completes by webhook). Plus Payouts API (developer earnings withdrawal) and marketplace payee routing (PAYPAL_PAYEE_EMAIL — payments go directly to the API seller's account). Mock mode exists purely so judges can run everything with zero setup.

  • APIMatic — the supply-side engine: Transformer (spec normalization from any format via POST /transformations/transform-via-file), Codegen API (typed TypeScript + Python SDK zips per listing, downloadable from the listing page), Code Context / context plugins (the LLM-legible llms.txt served to agents via tb_get_api_context). Calls APIMatic's public API (the same one the APIMatic CLI uses) — set APIMATIC_API_KEY to go live; a key-optional local generator keeps everything working without it. The portal/ workspace additionally ships a CLI-generated developer portal.

  • AI — the buyer agent runs on the LLM of your choice: Gemini (GEMINI_API_KEY, default gemini-3.8-flash) or Claude (ANTHROPIC_API_KEY) — driving the Tollbooth MCP server as its tool surface; discovery uses the agent-legible context files; the marketplace UI updates live as agents purchase and consume.

Submission checklist mapping

  • ✅ Meaningful PayPal integration: Orders, Webhooks, Payouts, sandbox-ready

  • ✅ Meaningful AI: autonomous Claude agent + agent-native discovery/docs

  • ✅ Working prototype: npm run demo (zero keys) or sandbox mode with credentials

  • ✅ Public repo, MIT license, complete run instructions

  • ✅ Hosted demo: Render blueprint in render.yaml (self-seeding, zero-credential default)

  • 🎬 Demo video: see docs/SUBMISSION.md for the script

License

MIT — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers