# Halfway API

Find a fair halfway meeting place between two addresses or place names. One call returns exactly three real, reachable venues ranked to minimize the travel-time difference between the two origins.

Use this when an agent needs to choose a mutually fair cafe, restaurant, coworking space, park, or EV charger without acquiring a maps API key. The service combines geocoding, routing, nearby-place search, and travel-time comparison behind one x402 payment.

- No API key, account, or subscription
- Pay only when a successful result settles
- $0.03 USDC on Base per successful response
- Driving, walking, and bicycling travel-time comparison

## Canonical endpoint

POST https://halfwayapi.com/v1/meet-halfway

- Price: $0.03 USDC per settled successful response
- Network: Base mainnet (eip155:8453)
- Payment: x402 v2, exact scheme
- Request content type: application/json
- Paid rate limit: 10 calculations per payer per minute

## Request

```json
{
  "origins": ["Union Square, New York, NY", "Astoria, Queens, NY"],
  "mode": "drive",
  "venueType": "cafe"
}
```

- `origins`: exactly two distinct location strings, 1-240 characters each
- `mode`: `drive`, `walk`, or `bicycle`
- `venueType`: `cafe`, `restaurant`, `coworking`, `park`, or `ev_charger`

Origins must resolve between 50 meters and 250 kilometers apart. The route itself must be no longer than 400 kilometers.

## x402 flow

1. Send the JSON request without credentials.
2. Read the HTTP 402 `PAYMENT-REQUIRED` header.
3. Create the declared x402 payment and retry the same request with `PAYMENT-SIGNATURE`.
4. On HTTP 200, read the result and `PAYMENT-RESPONSE` header.

Invalid requests, upstream failures, and requests that cannot produce three reachable venues are not settled. Buyers need USDC on Base; they do not need a token called Base or separate ETH for the standard gas-sponsored x402 flow.

## Successful response

HTTP 200 returns resolved origins, a route-time midpoint, and exactly three candidates. Candidates are ranked by:

1. Smallest travel-time difference between the origins
2. Lowest worst-case travel time
3. Lowest combined travel time
4. Closest distance to the route midpoint

Travel times are provider estimates. Drive mode uses free-flow rather than live traffic. Results come from a bounded pool of up to five venues near one route-time midpoint and are not a global optimum. Provider opening-hours data does not assert that a venue is currently open.

Do not use this endpoint for live traffic, ratings or reviews, a guarantee that a venue is currently open, or a globally exhaustive place search.

## Machine-readable resources

- OpenAPI 3.1: https://halfwayapi.com/openapi.json
- LLM manifest: https://halfwayapi.com/llms.txt
- Service icon: https://halfwayapi.com/icon.svg
- Health: https://halfwayapi.com/healthz

Data: Geoapify and OpenStreetMap contributors.