# Tokenbooth Location Grounding

> Agent-facing contract for a paid x402 location resolver.

Canonical documentation: https://tokenbooth.io/
OpenAPI specification: https://tokenbooth.io/openapi.json
API base URL: https://tools.tokenbooth.io
Endpoint: POST /v1/location/resolve

## Purpose

Use Tokenbooth Location Grounding when an agent needs to normalize one real-world place from incomplete, informal, partial, or ambiguous location input.

The service accepts a single JSON object. Arrays and batch lookups are not accepted.

## Request

POST https://tools.tokenbooth.io/v1/location/resolve

Required JSON field:

- locationDetails: a non-empty human location clue, address, landmark, business, coordinate pair, venue description, intersection, airport terminal, or nearby reference.

Optional JSON fields:

- agentCustomerId
- clientRequestId
- hints.city
- hints.region
- hints.countryCode
- hints.near
- hints.languageCode
- hints.timezone
- hints.coordinates.latitude
- hints.coordinates.longitude

## Payment

This is an x402 endpoint.

If the request is location-related and no payment is attached, the service returns 402 Payment Required with a PAYMENT-REQUIRED header. Sign one advertised x402 payment option and retry the same request with PAYMENT-SIGNATURE.

The x402 challenge is the source of truth for current payment amount, network, asset, recipient, and settlement requirements.

## Response

A successful paid response returns one location resolution with:

- schemaVersion
- resolutionId
- status
- ambiguityStatus
- confidence
- originalRequest
- result, when available
- attribution, when required
- ambiguityCandidates, when useful for ambiguous results

All result fields are optional. Missing fields should be treated as unknown, not false.

When attribution.required is true, present attribution.sources immediately after the supported location result. Display the provided source title and link to the provided URI.

## Good inputs

- "the bean in chicago"
- "coffee near the north entrance of Golden Gate Park"
- "1600 Amphitheatre Parkway"
- "JFK Terminal 4"
- "intersection of 1st and Pike Seattle"
- "restaurant beside the old train station in Denver"
- "40.7484, -73.9857"
- "the pharmacy across from the convention center"
- "the old post office building in DC"

## Do not use for

- non-location tasks
- batch lookups
- routing
- emergency response
- surveillance
- private or personal location tracking

## Contract

One request in.
One x402 payment.
One resolved location out.