# tollbooth

Paid tools for AI agents over HTTP 402. No signup, no API key: call the endpoint,
get a 402 with a payment challenge, pay (x402 USDC on Base, or Stripe MPP cards / USDC on Tempo), retry the same request with the
payment header, get the answer plus a receipt. A body that fails validation gets a
422 before any 402, so invalid input is never charged; an empty body or {} gets the
402, so you can read the price without building a request. While our routing
provider is down or out of quota, drive, matrix and airport answer 503 with a
Retry-After header before any 402, so nothing is charged; retry after that many seconds.

## Endpoints

- POST /v1/ping — $0.001 per call, x402 only. Empty body. Proves the pipe works.
- POST /v1/drive — $0.01 per call, x402 and MPP tempo. Body: {"origin": "MCO",
  "destination": "Hilton Downtown Orlando", "near": "Orlando, FL"}. Returns real
  road driving distance/time between two named places (airports, stations, hotels,
  addresses).
- POST /v1/matrix — $0.05 per call, x402 and MPP tempo. Body: {"origins": [...],
  "destinations": [...], "near": "..."}. Up to 100 origin x destination
  elements.
- POST /v1/license/verify — $0.05 per call, x402 and MPP tempo. Body:
  {"state": "FL", "license_number": "CGC012427"} or
  {"state": "FL", "name": "Fontana Construction Inc"}. Currently served:
  FL, OR only. Empty licenses is a paid 200, not a 404. Every response includes
  data_as_of; we will not sell data whose age we cannot state.
- POST /v1/entity/lookup — $0.01 per call, x402 and MPP tempo. Body:
  {"state": "FL", "entity_number": "P12345"} or
  {"state": "FL", "name": "Fontana Construction Inc"}. Returns the state
  business-registry record: status, formation date, principal address, registered
  agent, officers. Currently served: FL, OR only. Name is an exact match
  after normalizing case and punctuation; no fuzzy or prefix search. Returns up to
  10 entities, with truncated: true if more matched. Empty entities is a paid
  200, not a 404. Florida data covers active and inactive filings. Oregon data covers active businesses only; no match does not prove the entity never existed. Every response includes data_as_of and source.
- POST /v1/license/search — $0.10 per call, x402 and MPP tempo. Body:
  {"state": "FL", "trade": "roofing", "city": "Tampa"} or
  {"state": "OR", "trade": "residential_general", "zip": "97201"}; optional
  active_only (default true) and limit (1 to 25, default 25).
  Trades are fixed per state. FL: alarm, demolition, drywall, electrical, garage_door, gas_line, general, glazing, hvac, irrigation, low_voltage, marine, plumbing, pollutant_storage, pool, pool_specialty, residential_electrical, roofing, sheet_metal, sign_electrical, solar, specialty_structure, underground_utility, window_door; OR: commercial_general, commercial_specialty, home_inspector, lead_paint, locksmith, residential_general, residential_specialty. Another state's trade is a 422 that
  lists the valid ones. City is an exact match after normalizing case and spaces, on
  addresses in the requested state; zip matches the first 5 digits; no fuzzy or radius
  search. Returns up to 25 license holders (number, name, license type,
  class_code when a Florida trade is one class of a license type, status, expiry, city,
  zip), active first, then latest expiry, then name, with total_matches and truncated.
  Empty results is a paid 200, not a 404. Florida data covers active and inactive licenses. Oregon data covers active licenses only; an expired license may be missing rather than listed as expired. Every response includes
  data_as_of and source.
- POST /v1/airport/nearest — $0.02 per call, x402 and MPP tempo. Body:
  {"location": "Lakeland, FL", "near": "Florida", "k": 3, "airport_size": "scheduled"};
  near is optional, k is 1 to 5 (default 3), airport_size is "scheduled" (any
  airport with scheduled passenger service, the default) or "large" (large airports only).
  Returns up to k airports within 300 km, ranked by real road drive time:
  IATA and ICAO codes, name, city, type, drive distance and minutes, plus airports_data_as_of
  (when our OurAirports file was fetched). Drive times are always road routes, never a
  straight-line guess: an airport with no road route (another island) is left out, so
  you may get fewer than k, or an empty list (a paid 200). No airport in range, or a place
  that cannot be found, is a 422.

MCP: POST /mcp (streamable HTTP, stateless) serves these endpoints as MCP tools at the
same prices, paid with x402 in _meta["x402/payment"]; initialize and tools/list are free.

Machine-readable manifest with JSON schemas: GET /
OpenAPI: GET /openapi.json
Data: OpenStreetMap (ODbL), OurAirports (public domain). Attribution string is included
in every response.