# HomeShared

> HomeShared is a vacation rental marketplace where guests pay no service fee. Its public agent API and MCP server take an Airbnb listing link and find the same home bookable for less (on HomeShared or on the host's own booking site), search homes free for given dates, quote an all-in price, and return a checkout link for the traveler. No API key or account is needed. The tools never book anything and never take payment details.

Prices are checked live on each call (see `checked_at`) and include fees and taxes. Amounts are in USD and dates are YYYY-MM-DD. The traveler always confirms and pays on the checkout page that `book` returns.

## MCP server

- URL: https://homeshared.app/mcp (Streamable HTTP, stateless, JSON responses; send JSON-RPC with POST)
- Tools: `find_cheaper` (an Airbnb link and dates: the same home elsewhere, with its all-in price), `search_stays` (homes free in a place), `get_quote` (itemised price and a quote_id), `book` (a checkout link for the traveler)
- Claude Code: `claude mcp add --transport http homeshared https://homeshared.app/mcp`
- Claude.ai and Claude Desktop: Settings → Connectors → Add custom connector, URL https://homeshared.app/mcp

## REST API

Base URL https://homeshared.app/api/v1. JSON in and out, open CORS, no auth. Each endpoint returns the same JSON as the MCP tool of the same name.

- `POST /find-cheaper` with `{"airbnb_url", "check_in", "check_out", "adults", "children"?, "infants"?, "pets"?, "airbnb_total"?}`: offers for the same home off Airbnb, each with its all-in `total`, `savings_vs_airbnb`, a `match` level and confidence, a `url`, and an `offer_id`. `airbnb_total` is what Airbnb shows at checkout: savings are measured against it when given. Without it, savings are reported only for homes that copy their prices from their Airbnb calendar, against Airbnb's prices for the same nights, and are otherwise null. No offers means no host has listed the home here yet; `not_on_homeshared.request_url` is where a traveler can ask the host to join.
- `GET /search-stays?location=Lisbon&check_in=…&check_out=…&adults=2` (optional `children`, `infants`, `pets`, `min_bedrooms`, `max_total`, `limit` up to 20): homes free for the trip, cheapest all-in first.
- `POST /quote` with `{"offer_id", "check_in", "check_out", "adults", ...}`: a fresh itemised price and a `quote_id` valid for 15 minutes.
- `POST /book` with `{"quote_id"}`: re-checks the price and returns `checkout_url`, where the traveler signs in, reviews the house rules and cancellation policy, and pays. It reserves nothing; `price_changed_since_quote` says whether the price moved.

Example:

```bash
curl -s -X POST https://homeshared.app/api/v1/find-cheaper -H 'content-type: application/json' \
  -d '{"airbnb_url":"https://www.airbnb.com/rooms/12345678","check_in":"2027-03-12","check_out":"2027-03-15","adults":2}'
```

## Errors and limits

- Errors are `{"error": {"code", "message", "details"?}}`: `invalid_request` (400), `unsupported_url` (400), `card_data_not_accepted` (400), `not_found` (404), `unavailable` (409), `quote_expired` (410), `rate_limited` (429).
- Requests carrying card numbers or payment fields are refused.
- Rate limits: 60 requests a minute and 1,000 a day per IP address, across /mcp and /api/v1; and 30 `find_cheaper` lookups of one Airbnb listing per 10 minutes. Over a limit the answer is HTTP 429 with a `Retry-After` header (seconds); on /mcp the body is a JSON-RPC error.

## Policies and contact

- [Developer docs](https://homeshared.app/developers): the same, for people
- [Privacy policy](https://homeshared.app/privacy#ai-assistants): what an agent lookup keeps
- [Help Center](https://homeshared.app/help)
- Support: support@homeshared.app