LivStay

An open protocol for personal agents to find, ask about and book independent homes.

Draft 0.2 · 24 October 2026 · Extension livstay.org/stays, version "0", revision "0.2" · Builds on Personal Agent Protocol (Poppy) draft 0.2 · Licensed under the Apache License 2.0

Status: draft. This document is a working draft for implementers and reviewers. Until 1.0 a revision can break compatibility with earlier drafts; §4.3 says how both sides tell revisions apart. LivAround is the reference implementation; the protocol is not owned by it. Feedback: open an issue. Changes from draft 0.1 are listed in Appendix D.

1. Introduction

Travellers are starting to plan and book stays through personal agents: assistants that act for one person. Today those agents mostly reach homes through online travel agencies (OTAs), which own the listing, the guest relationship and the price. Independent hosts and the platforms that serve them have no standard way to be found by an agent, answer its questions or take its booking directly.

LivStay is that standard. It is an extension of Poppy: Poppy defines how a personal agent discovers a company, signs a user in, holds a session and talks to the company; LivStay defines what a stay is on top of that: the home, its facts, its availability, its terms, how an agent asks the host a question and how a booking is proposed, approved and completed.

1.1 Goals

• Recommendation before booking. An agent can tell a traveller why a home fits, from facts the host stands behind, before any booking call is made.
• The traveller approves; the price is binding. No agent can commit a traveller's money to a price the traveller has not seen, and the price shown is the price charged.
• The host's rules hold on every channel. An agent sees the same terms the host publishes everywhere else, and the host decides who can book instantly.
• A human where it matters. An agent can put a question to the host, a person, before booking, and get an answer it can cite.
• Start with what you have. A host platform can publish facts alone and add prices, enquiries and bookings later (§3.3).
• Reuse, don't reinvent. Identity, sign-in, sessions, conversations and confirm-before-act are Poppy's. LivStay adds only what is specific to stays.

1.2 Non-goals

• Search ranking. LivStay does not say how agents rank homes.
• Rate parity. LivStay takes no position on any contract between a host and an OTA.
• Payment rails. LivStay does not define a payment protocol (§11).
• Hotels. Nothing prevents a hotel from implementing LivStay, but the objects are shaped for homes rented by their owners or managers: one calendar, one host, house rules, a deposit.
• Member-only exchange. Home swaps, points and circles are out of scope for this draft.

1.3 Relationship to Poppy

LivStay is a third-party Poppy extension, named under a domain its authors control, as Poppy 3.3 requires. It depends on:

Where this document and Poppy disagree, Poppy governs everything Poppy defines.

2. Conventions and terms

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

JSON examples are illustrative. Field tables and the JSON Schemas (§16) are normative; where a schema and the text disagree, the text governs and the schema is a defect.

2.1 Dates, times and money

• Dates (check_in, check_out, availability days) are ISO 8601 calendar dates in the Home's time_zone (§6.1.1). Times of day (check-in from, check-out by) are local to the same zone.
• Timestamps (expires_at, complete_by, at) are RFC 3339 in UTC with a Z suffix.
• Money is a Money object { "amount": string, "currency": string }:
• currency is an ISO 4217 alphabetic code.
• amount is a decimal string with exactly as many fraction digits as the currency's ISO 4217 minor unit: "129500.00" for INR, "18500" for JPY, "12.500" for KWD. It matches ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$, with no exponent, sign +, spaces or group separators.
• Negative amounts appear only where a field says they may (discounts, price differences).
• Rounding. A Host Platform computes each Quote line in whatever precision it likes, then rounds that line to the minor unit before anything is summed. It may choose the rounding method; it MUST round lines before reconciling them, never the total alone.
• Reconciliation. In every Quote, and in the livstay terms of every booking operation: 1. every Money value has the Quote's currency; 2. the sum of the amount of every line with in_total: true equals total exactly; 3. the sum of payment_schedule amounts equals total exactly; 4. every cancellation refund is between zero and total, and refunds never increase as the deadline gets later; 5. due_now equals the sum of payment_schedule entries due at booking.

An agent MUST NOT confirm a booking whose Quote fails any of these, and SHOULD report it with a mismatch report (§6.6). - Signed objects contain no fractional numbers. Quotes, Receipts and signed answers carry money as strings and counts as integers, so their canonical form (§13.1) is exact.

2.2 The Party

{ "adults": 2, "children": [{ "age": 7 }, { "age": 1 }], "pets": 1 }

A Host Platform MUST price and check eligibility from the whole Party: a stay that breaks max_guests, max_infants, pets.max or min_adult_age fails with stay_invalid, and a price that depends on children's ages or pets MUST show the difference as Quote lines. Agents SHOULD send only the ages, never names or dates of birth.

3. Overview

3.1 The parties

 Traveller ──▶ Personal Agent ──Poppy──▶ Host Platform ──▶ Host
                   │                          │
                   │  read: homes, quotes     │  facts, calendar, terms,
                   │  ask: conversation       │  answers to enquiries,
                   │  book: operations        │  booking messages
                   │  follow: booking events  │

The Host Platform speaks for the Host. Conversations reach the Host as a person (§8.2).

3.2 A stay, in six steps

1. Find. The agent reads poppy.json, then lists Homes and reads their Facts. No token.
2. Price. The agent asks for a Quote for exact dates and Party. No token. The Quote is binding for up to 24 hours and holds nothing.
3. Ask (optional). In a signed-out Session, the agent opens a conversation and puts the traveller's question to the Host.
4. Book. The traveller signs in. The agent proposes a booking from the Quote; the Host Platform answers with a Poppy operation in state proposed, which holds the calendar for up to 15 minutes. The agent shows the traveller the summary; the traveller approves; the agent confirms.
5. Complete. The traveller pays, and verifies identity if the Host requires it, before a deadline the Host Platform states. The operation then succeeds.
6. Stay. The agent follows the booking's event feed and opens a conversation with the Host when needed. Changes and cancellations are new operations. Every write and every money movement carries a Receipt.

3.3 Levels

A Host Platform declares the highest level it supports. Each level includes the ones below.

Levels 0 and 1 need no Poppy Session and no token. Level 0 can be served from static files. A Host Platform SHOULD publish Level 0 before anything else: it is what lets an agent recommend a home.

4. Advertising support

4.1 Host Platform

A Host Platform advertises LivStay in the extensions object of its poppy.json:

{
  "protocol_version": "0.2",
  "organization": { "name": "LivAround", "domain": "stay.livaround.com" },
  "auth": {
    "issuer": "https://stay.livaround.com",
    "direct": { "scopes": ["poppy:read", "livstay:book", "livstay:share_contact", "livstay:share_trip_context"] },
    "custom_scopes": {
      "livstay:book": "Book, change and cancel stays you approve",
      "livstay:share_contact": "Give the host your phone number and email",
      "livstay:share_trip_context": "Tell the host the purpose of your trip and when you arrive"
    }
  },
  "apis": [
    { "type": "openapi", "url": "https://stay.livaround.com/livstay/v0/openapi.json" },
    { "type": "mcp", "url": "https://stay.livaround.com/livstay/v0/mcp" }
  ],
  "agent": { "protocols": [{ "type": "poppy", "endpoint": "https://stay.livaround.com/poppy/conversations" }] },
  "web": { "browser_session_endpoint": "https://stay.livaround.com/poppy/browser-session" },
  "extensions": {
    "operations": { "version": "1", "endpoint": "https://stay.livaround.com/poppy/operations" },
    "livstay.org/stays": {
      "version": "0",
      "revision": "0.2",
      "endpoint": "https://stay.livaround.com/livstay/v0",
      "level": 3,
      "keys": "https://stay.livaround.com/.well-known/livstay-keys.json",
      "terms_of_service": "https://livaround.com/terms",
      "facts_site": "https://booking.livaround.com"
    }
  }
}

Example 1. A Host Platform's poppy.json.

A Host Platform at level 3 MUST list operations with version "1", agent.protocols with a poppy entry, and auth.direct (or another sign-in type) able to grant livstay:book.

4.2 Personal Agent

A Personal Agent that supports LivStay lists it in its client metadata document:

"extensions": {
  "operations": { "version": "1" },
  "livstay.org/stays": { "version": "0", "revisions": ["0.2"] }
}

revisions is REQUIRED: the drafts the agent implements. A Host Platform MUST NOT return a booking operation or LivStay conversation data to an agent that does not list livstay.org/stays with a revision the Host Platform serves; it answers extension_required (Poppy 3.3). Levels 0 and 1 are public (§5.1) and need no client metadata.

4.3 Revisions

The extension version stays "0" for every draft, so before 1.0 it cannot tell drafts apart. revision does.

• An agent MUST send the header LivStay-Revision: <revision> on every request to a LivStay endpoint, naming one revision both sides support. A Host Platform MUST answer in that revision and echo the header.
• A request without the header is answered in the Host Platform's revision, with the header set. An agent MUST check it before relying on the response.
• A request naming a revision the Host Platform does not serve fails with revision_unsupported (400), whose body lists supported.
• In a conversation, LivStay data carries "revision" alongside "type".
• From 1.0, revision changes only for compatible additions, and version changes for breaking ones, as Poppy 3.3 defines.

5. Access and scopes

5.1 What needs what

Poppy's scopes are account scopes: a signed-out Session Token carries none (Poppy 4.2). LivStay therefore names three kinds of access.

• A Host Platform MUST serve public endpoints without a token. It MAY accept a Session Token on them, signed in or out, and use it only to set rate limits and to resolve a signed-in traveller's tier (§7.2); it MUST NOT require one or check its scope.
• A Host Platform MUST accept a signed-out Session Token for enquiries and reports, and MUST NOT ask for sign-in to answer a pre-booking question.

5.2 Account scopes

Every write is a named scope the traveller sees at sign-in. A Host Platform MUST NOT require poppy:write for any LivStay action.

Without livstay:share_contact, Host and traveller talk through the Host Platform's relay and neither sees the other's direct details.

6. The Home

6.1 Listing Homes

GET {endpoint}/homes (public)

The response is { "homes": [Home summary], "next_cursor": string | null }. A Home summary is the Home object (§6.1.1) without facts.faq and attestations.

GET {endpoint}/homes/{home_id} (public) returns one Home.

6.1.1 Home object

6.1.2 Host object

6.2 Facts

Facts are what an agent quotes when it tells a traveller why a Home fits. Every Fact is a statement the Host stands behind; none is generated by the Host Platform without the Host's review.

Agents SHOULD cite Facts by home_id and facts_version when they rely on them.

6.3 Terms

Terms are the same for every agent and the same as on the Host Platform's own site. A Host Platform MUST NOT publish different Terms for the same Home to different agents.

6.4 Protection

Every Home declares who carries the risk of damage and how claims are decided. A Home without a Protection object MUST NOT be published.

6.5 The same facts on the web

A Home's url MUST serve the same Facts, Terms and Protection as the endpoint, as crawlable HTML with schema.org markup, so an answer engine that never calls the API cites the same statements an agent reads. A Host Platform SHOULD check this on every change. Where they differ, the endpoint governs a booking and the difference is a defect.

6.6 Reporting a mismatch

An agent that finds a Fact contradicted by the Home's page, photos or a Host answer, or a Quote that fails reconciliation (§2.1), SHOULD report it with POST {endpoint}/homes/{home_id}/mismatch, body { "facts_version", "quote_id", "field", "description" } (either facts_version or quote_id), with a Session Token, signed in or out, and no scope. The rules for Poppy feedback (Poppy 8) apply: no personal data, treated as data by the Host Platform, one report per finding. The response is 202 with no body.

A stay task the Host Platform offers no way to do (a split payment, a long-stay discount it does not publish) is reported through Poppy's own feedback endpoint with kind: "missing".

7. Availability and quotes

7.1 Availability

GET {endpoint}/homes/{home_id}/availability?from={date}&to={date} (public)

The range MUST NOT exceed 400 nights. The response:

Availability is indicative. Only a Quote is binding.

7.2 Quotes

POST {endpoint}/homes/{home_id}/quotes (public)

{
  "check_in": "2026-12-27",
  "check_out": "2027-01-03",
  "party": { "adults": 4, "children": [{ "age": 7 }, { "age": 1 }], "pets": 0 }
}

The response is 201 with a Quote. A Quote does not block the calendar; it fixes the price.

Binding. A Host Platform MUST honour a Quote's total, payment_schedule, cancellation and deposit for any booking proposed from it before expires_at, if the dates are still available and the traveller's tier at booking is at least assumed_tier. If the dates are not available, the proposal fails with dates_unavailable; the price never changes.

Fees are lines. Any fee the Host Platform or an agent charges MUST appear as its own line. The agent_fee line, if any, is set by the agent's agreement with the Host Platform and MUST be shown to the traveller before approval.

Retention. A Host Platform MUST keep every Quote it issued for at least 30 days after expires_at, and every Quote a booking references for the life of that booking's Receipts (§13.4). GET {endpoint}/quotes/{quote_id} (public) returns a kept Quote.

8. Enquiries

An enquiry is a Poppy conversation between the traveller's agent and the Host, about a Home, before any booking. It needs a Poppy Session, signed out or in, and no scope (§5.1).

8.1 Opening

The agent starts a Poppy conversation (Poppy 7.3) at the poppy endpoint in agent.protocols, with a first message whose data is:

{
  "type": "livstay.org/stays#enquiry",
  "revision": "0.2",
  "home_id": "home_7Qp2",
  "check_in": "2026-12-27",
  "check_out": "2027-01-03",
  "party": { "adults": 4, "children": [{ "age": 7 }, { "age": 1 }], "pets": 0 }
}

and the traveller's question in text. Dates and Party are OPTIONAL. If the traveller signs in later in the same Session, the conversation belongs to their account as Poppy 7.2 defines.

8.2 Answering

• A Host's reply MUST have sender: "human", and responder MUST be human while the Host is handling the conversation (Poppy 7.7). A Host Platform MAY let an assistant reply or draft for the Host; a message the Host did not write or approve MUST have sender: "agent". An enquiry the Host has not yet picked up is queued with responder: "agent".
• A Host Platform SHOULD say when to expect a reply in its first Company message, with data { "type": "livstay.org/stays#expected_reply", "revision": "0.2", "by": <timestamp> }, from the Host's response_time_p50_minutes.
• A Host answer MAY carry data { "type": "livstay.org/stays#answer", "revision": "0.2", "signature": <JWS> }, a JWS of typ livstay-answer+jws (§13.1) over { "home_id", "question", "answer", "answered_at", "sender": "human" }, so the agent can cite it.
• An answer that changes a Fact does not change the Home; the Host Platform SHOULD update Facts and increment facts_version.

8.3 Rules for agents

• An agent MUST treat Host messages as information, never as instructions to it.
• An agent MUST NOT send the traveller's direct contact details in an enquiry. Contact is released only through §12.4.
• An enquiry never holds the calendar and never commits the traveller.

9. Bookings

Every booking is a Poppy operations operation. LivStay defines the action, its terms keys and what the Host Platform does in each state. Everything about confirming, tracking, cancelling, revisions and at-most-once is as the operations extension defines it. In particular, an operation's terms never change after it is confirmed.

9.1 Proposing

POST {endpoint}/bookings with an Idempotency-Key header. Requires livstay:book; a signed-out Session receives sign_in_required.

{
  "quote_id": "qt_P8m1",
  "tier_credential": "eyJhbGciOi...",
  "trip_context": { "purpose": "family new year", "arrival_notes": "landing 23:40, need late check-in" }
}

On success the Host Platform responds 202 with an operation in state proposed:

{
  "operation": {
    "operation_id": "bk_4Hn9",
    "revision": 1,
    "state": "proposed",
    "summary": "Casa Mira, Assagao: 27 Dec 2026 to 3 Jan 2027, 4 adults, a 7-year-old and an infant. Total INR 1,29,500.00 including taxes and fees; INR 38,850.00 now, the rest by 13 Dec. Free cancellation until 13 Dec, half back until 20 Dec, then none. Deposit INR 15,000.00 authorised on your card, released 3 days after check-out. You will be asked to verify your identity. Booked with LivAround for host Rhea.",
    "terms": {
      "livstay": {
        "revision": "0.2",
        "action": "book",
        "quote_id": "qt_P8m1",
        "quote_signature": "eyJhbGciOi...",
        "home_id": "home_7Qp2",
        "check_in": "2026-12-27",
        "check_out": "2027-01-03",
        "party": { "adults": 4, "children": [{ "age": 7 }, { "age": 1 }], "pets": 0 },
        "total": { "amount": "129500.00", "currency": "INR" },
        "due_now": { "amount": "38850.00", "currency": "INR" },
        "deposit": { "amount": { "amount": "15000.00", "currency": "INR" }, "mode": "authorise" },
        "terms_version": 12,
        "tier": { "presented": true, "accepted": true, "applied": "trusted" },
        "requirements": ["payment", "identity_verification"],
        "awaiting": "traveller",
        "proposed_by": "traveller_agent"
      }
    },
    "expires_at": "2026-10-24T10:15:00Z",
    "user_approval_required": true,
    "url": "https://stay.livaround.com/b/bk_4Hn9",
    "confirmation": null,
    "result": null
  }
}

Example 2. A proposed instant booking. The calendar is held until expires_at.

If tier.applied is lower than the Quote's assumed_tier, the Host Platform MUST NOT apply the Quote's tier-dependent terms: it fails the proposal with tier_mismatch, and the agent asks for a new Quote at the lower tier.

9.2 Holds

While a booking operation is proposed with awaiting: "traveller", or in_progress, the Host Platform MUST block the Stay's dates against every other channel it controls. That period is the hold.

• For an instant booking, expires_at MUST be at most 15 minutes after the proposal.
• After confirmation the hold continues until the operation is final or complete_by passes (§9.5). It is never extended by a revision.
• When the operation becomes expired, cancelled or failed, the hold ends.
• A Host Platform MUST limit open holds per traveller and per client_id (§15.3).

A traveller who wants time to decide uses a Quote (24 hours, binding price, no hold), not a hold.

9.3 Approval

• A Host Platform MUST set user_approval_required: true on any booking operation whose terms move money or authorise a deposit. A standing permission is never enough to spend a traveller's money on a stay.
• The summary MUST state the Home, dates, Party, total, what is due now, the cancellation terms in dated form, the deposit, any identity verification, and the Host Platform and Host names. A traveller who reads only the summary MUST have everything needed to decide.
• Every book or change revision is bound to exactly one Quote, named by quote_id and quote_signature. For revision 1 it is the Quote the booking was proposed from; a counter revision carries a new Quote for its own terms (§10.2). The revision's check_in, check_out, party, total, due_now and deposit MUST equal that Quote's.
• Before confirming, an agent MUST verify quote_signature (§13.2) and reconcile the Quote (§2.1), and MUST NOT confirm if either fails, if the revision's terms differ from its Quote, or if the Quote differs from the one the traveller was shown for this revision.
• The agent confirms with approved_by: "user" as the operations extension defines.

9.4 Trip context

trip_context lets the Host prepare (an airport pickup, a cot, a late arrival). It is OPTIONAL and MUST NOT be required to book.

A Host Platform MUST share trip_context only with the Host of that booking and MUST NOT use it for advertising. It MUST delete it:

• within 24 hours after the proposing operation ends failed, cancelled or expired; or
• no later than 90 days after check-out, or after the booking is cancelled.

9.5 Completion: payment and identity

Poppy operations cannot change after confirmation, so what happens between confirmation and success is reported beside the operation, not in it.

When the traveller's agent confirms a revision whose requirements is not empty, the Host Platform moves the operation to in_progress and creates a completion record:

GET {endpoint}/bookings/completion/{operation_id} (account, poppy:read)

{
  "operation_id": "bk_4Hn9",
  "complete_by": "2026-10-24T10:42:00Z",
  "requirements": [
    { "type": "payment", "status": "pending", "url": "https://stay.livaround.com/pay/bk_4Hn9",
      "amount": { "amount": "38850.00", "currency": "INR" } },
    { "type": "identity_verification", "status": "done", "url": null }
  ]
}

• The pages open in the traveller's browser joined to their Poppy Session where the Host Platform lists web.browser_session_endpoint (Poppy 5), so the traveller is already identified. The operation's url SHOULD lead to the same steps.
• While requirements are pending, the operation's Retry-After (operations extension, Tracking) SHOULD be short, and a Host Platform MAY also send an action_needed event (§12.2).
• When every requirement is done, the operation MUST move to succeeded.
• If complete_by passes first, or a requirement is failed, the operation MUST move to failed, the hold ends, anything taken is returned, and result.summary says so.
• An agent MUST NOT collect card, bank or identity-document details itself.

A revision with empty requirements goes from confirmed to succeeded as soon as the Host Platform books it.

9.6 States

10. Requests and counter-offers

10.1 Requests

When the Quote's instant is false, proposing a booking makes a request: an operation in state proposed with awaiting: "host", which does not hold the calendar and cannot yet be confirmed. Its expires_at is at most 72 hours ahead. Confirming it fails with awaiting_host.

The Host either:

• accepts: the Host Platform issues a new revision with the same terms and awaiting: "traveller", holds the calendar, and sets expires_at at most 15 minutes ahead, or at most 24 hours ahead if it also sends an action_needed event (§12.2);
• counters: a new revision with different terms (§10.2); or
• declines: the operation becomes cancelled.

The agent learns of the Host's decision by reading the operation (operations extension, Tracking).

10.2 Counter-offers

A counter is a new revision of the same operation, issued before confirmation. Each counter revision MUST carry:

Rules:

• Only kinder. A counter from host or host_agent MUST NOT be worse for the traveller than the Home's published Terms for the same Stay: no higher total, no stricter cancellation, no larger deposit.
• At most three counters per operation, from either side. After the third, no party may counter again: a revision awaiting the Host can still be accepted or declined as in §10.1, and a revision awaiting the traveller can be confirmed or cancelled. An acceptance is not a counter.
• A traveller's agent proposes a counter with POST {endpoint}/bookings/{operation_id}/counter (account, livstay:book) carrying any changed check_in, check_out, party or a requested total, and a note. The Host Platform answers with the operation, unchanged or as a new revision with proposed_by: "traveller_agent" and awaiting: "host".
• Every revision needs the traveller's fresh approval before confirmation (§9.3), and is checked against its own Quote, never the one the operation started from.

10.3 Countering within bounds

If decision_mode is auto_counter, the Host Platform MAY issue counters as host_agent without the Host, only within bounds the Host set (for example a lowest acceptable total, shorter dates, a split stay). The bounds themselves are not published. Each such counter MUST carry a reason and MUST be visible to the Host in the same record.

11. Payment

Poppy leaves payments as an open topic, so this draft defines only the hand-off, through the completion record (§9.5).

• due_now is taken during completion, on the Host Platform's own page.
• An agent MUST NOT collect card or bank details from the traveller for the Host Platform.
• Later instalments follow payment_schedule. The Host Platform announces each with a payment_due event (§12.2) carrying the amount, the date and a payment page URL. A missed instalment is handled as the Terms say; it MUST NOT cancel the booking without a cancelled_by_host event that states why and what is refunded.
• Every amount collected, authorised, captured, released or refunded produces a Receipt (§13.3).

When Poppy defines payments, a later draft will adopt it and this section will become a fallback.

12. After booking

12.1 The booking

When a booking operation succeeds, result.data.livstay carries:

GET {endpoint}/bookings (account, poppy:read) lists the signed-in traveller's bookings with this Host Platform. GET {endpoint}/bookings/{booking_id} returns one, with its current dates, Party, status and the IDs of operations that changed it.

12.2 Booking events

Every booking has an event feed. It is how the agent learns what the Host or the Host Platform did.

GET {endpoint}/bookings/{booking_id}/events?cursor={cursor}&wait={seconds} (account, poppy:read)

The response is { "events": [Event], "cursor": string, "has_more": boolean }, with the same reading rules as Poppy conversation events (Poppy 7.5): cursor is the last event returned, wait (0–30) holds the request open until an event arrives, and has_more: true means read again at once.

Poppy has no push channel yet (Poppy path to 1.0). Agents read the feed with wait.

12.3 The booking conversation

Poppy conversations are started by the Personal Agent (Poppy 7.3), so the agent opens the booking conversation; the Host Platform never does.

• The agent starts a Poppy conversation with a first message whose data is { "type": "livstay.org/stays#booking", "revision": "0.2", "booking_id": "bkg_…" }, in a signed-in Session whose account holds the booking. A Host Platform MUST reject it with booking_not_found (404) otherwise.
• The conversation reaches the Host as a person, under the rules of §8.2.
• A booking has at most one open booking conversation per client_id. Opening another returns conversation_exists (409) with its conversation_id.
• When the Host writes and no booking conversation is open, the Host Platform keeps the message, sends a message_waiting event, and delivers the message as the first Company message once the agent opens the conversation.
• Machine events stay in the feed (§12.2); a Host Platform SHOULD NOT duplicate them as messages.

12.4 Contact

The Host and the traveller talk through the Host Platform's relay by default.

PUT {endpoint}/bookings/{booking_id}/contact (account, livstay:share_contact)

{ "share": ["phone", "email"] }

The Host Platform releases those of the traveller's details it holds to the Host of this booking, and returns 200:

{
  "shared": ["phone", "email"],
  "host_contact": { "name": "Rhea", "phone": "+91…", "email": null },
  "receipt": "eyJhbGciOi..."
}

host_contact holds the Host's details the Host has agreed to share with booked guests; a field the Host has not agreed to is null. GET on the same path returns the current state; DELETE revokes:

• after revocation the Host Platform MUST NOT release the traveller's details again, MUST tell the Host that the traveller withdrew them, and returns 200 with { "shared": [], "receipt" };
• details already released cannot be recalled; the response says so in note;
• both PUT and DELETE produce a Receipt and a contact_shared or contact_revoked event.

12.5 Changes and cancellations

• Change: POST {endpoint}/bookings/{booking_id}/changes (account, livstay:book) with the new check_in, check_out or party. The Host Platform issues a Quote for the changed Stay and answers with a new operation (action: "change") bound to it, whose terms add price_difference (Money, may be negative) and state the new cancellation deadlines. A price difference due is collected through completion (§9.5).
• Cancel: POST {endpoint}/bookings/{booking_id}/cancellation (account, livstay:book). The Host Platform answers with an operation (action: "cancel") whose terms add refund (Money), computed from the cancellation terms the traveller approved: those of the Quote bound to the booking's confirmed revision, or of a later confirmed change. A Host Platform MUST NOT apply a stricter policy published after booking. It MAY apply a more generous one.
• Both need the traveller's approval like a booking.
• A Host-initiated cancellation is not an operation the agent confirms: it arrives as a cancelled_by_host event with a Receipt, the reason and the refund.

13. Signatures, receipts and attestations

13.1 Signed objects

Quotes, Receipts and signed Host answers are compact JWS [RFC7515].

• Algorithms. A Host Platform MUST sign with ES256 (ECDSA P-256, SHA-256) [RFC7518] and MAY also offer EdDSA with Ed25519 [RFC8037]. Agents MUST support ES256. none, and any symmetric (HS*) algorithm, MUST be rejected.
• Header. alg, kid and typ are REQUIRED. kid names a key in the Host Platform's keys JWK Set. typ is livstay-quote+jws, livstay-receipt+jws or livstay-answer+jws. No other header parameter is used; jku, x5u and jwk MUST be ignored.
• Payload. The UTF-8 bytes of the JSON Canonicalization Scheme [RFC8785] form of the signed object. Because signed objects contain no fractional numbers (§2.1), that form is: object members sorted by key (by UTF-16 code units), no insignificant whitespace, strings escaped as RFC 8785 specifies, integers in plain decimal.
• A Quote's payload is the Quote object with its signature member removed. A Receipt's and an answer's payload is the claims object itself.

13.2 Verifying

To verify a signed object, an agent:

1. splits the JWS, decodes the header, and rejects it unless alg is allowed, typ is the one expected, and kid is present;
2. fetches keys from the Host Platform's poppy.json (it MAY use a cached copy no older than the response's cache lifetime, and MUST refetch once on an unknown kid);
3. selects the JWK whose kid matches, and rejects the JWS unless the key's alg, if present, equals the header's alg;
4. verifies the signature;
5. decodes the payload and treats it as the authoritative object. For a Quote, it also canonicalizes the Quote it received, without signature, and rejects the Quote unless the two byte strings are equal.

A Quote that fails verification is not a Quote: an agent MUST NOT show it to the traveller as a price or propose a booking from it.

13.3 Receipts

A Receipt is a signed object of typ livstay-receipt+jws. A Host Platform MUST produce one:

• for every write it performs for an agent: proposal, confirmation, counter, change, cancellation, contact grant and revocation; and
• for every event the event table (§12.2) marks: payments, refunds, deposit authorisation, capture and release, claims and their decisions, and Host-initiated cancellations.

A Host Platform MUST NOT put a value in approved_by for a write that confirmed nothing. The Host sees the same records on the booking. A Receipt proves what the Host Platform did and on whose stated approval; like a Poppy confirmation, it does not prove what the traveller saw.

13.4 Keys and retention

• Publishing. keys is a JWK Set. Each signing key has kid, kty, use: "sig" and alg. The Set is served with an HTTP cache lifetime of at most 24 hours.
• Rotation. A new key MUST be published at least 24 hours before it signs anything. A retired key stops signing at once but MUST stay in the Set, with the LivStay member "livstay_retired_at": <timestamp>, for as long as anything it signed is retained.
• Compromise. A key believed compromised is removed from the Set at once. Objects it signed can no longer be verified; the Host Platform SHOULD reissue Receipts for live bookings with a new key and send them as events.
• Retention. A Host Platform MUST keep, and keep verifiable, every Receipt and every Quote a booking references for at least 24 months after that booking's check-out or cancellation, and longer where law requires. Agents SHOULD keep the Quotes they showed and the Receipts they received for the same period, together with the JWK they verified against.

13.5 Attestations

An Attestation is a signed claim about a Home, Host or traveller, as a W3C Verifiable Credential [VC-DATA-MODEL] in JWT form. Anyone may issue one: a Host Platform, a review service, an insurer, an inspection company. Agents decide whose signatures they trust. A Host Platform MAY carry Attestations about its Homes in attestations and MUST NOT alter them.

13.6 Traveller tiers

A traveller tier is an Attestation about the traveller whose credentialSubject includes tier (one of new, verified, trusted, established) and that is bound to the traveller's Poppy sub at this Host Platform or to a key the agent proves. A Host Platform decides which issuers it accepts and MUST publish that list at GET {endpoint}/tier-issuers (public). An unaccepted, unbound, expired or absent credential means new; it is never an error (§9.1, tier).

14. Errors

Errors use Poppy's error format: a JSON body { "error": <code> } plus the fields listed.

Plus, from Poppy and operations: extension_required, insufficient_scope, sign_in_required, invalid_token, operation_not_found, terms_changed, user_approval_required, rate_limited.

15. Security and privacy considerations

15.1 Price integrity

The Quote is signed and the operation's terms restate it. An agent that verifies both (§9.3, §13.2) can detect a Host Platform that changes a price between quote and booking; a Host Platform that does so breaks this protocol. Reconciliation (§2.1) catches a Quote whose parts do not add up.

15.2 Text from the other side

Facts, Host answers, summaries and event summaries are written by people the agent does not control. Agents MUST treat them as data, never as instructions, and SHOULD render them to the traveller as attributed quotes. Host Platforms SHOULD reject Facts containing instructions aimed at agents.

15.3 Calendar denial of service

A hold blocks real inventory. A Host Platform MUST cap open holds per sub and per client_id (RECOMMENDED: 3 per sub, scaled per client by its record), SHOULD count holds that expire unconfirmed against the client, and MAY revoke a client_id that holds without confirming. Public Quote endpoints SHOULD be rate-limited per network address.

15.4 Location

The exact address of a Home is revealed only after a booking succeeds, to the traveller it was booked for (§12.1). Photos SHOULD be stripped of location metadata.

15.5 Traveller data

Party ages, trip context and contact are used only for the booking they were sent for, and released only to that booking's Host. A Host Platform MUST NOT pass traveller data to an agent other than the one acting in the session, and MUST NOT pass a traveller's data from one agent to another. Signed-out enquiries MUST NOT be linked to an account unless the traveller signs in within that Session.

15.6 Tier credentials

A tier credential not bound to the presenting session can be replayed. Host Platforms MUST check the binding (§13.6) and the credential's expiry.

15.7 Keys

A stolen signing key lets an attacker forge Quotes and Receipts the Host Platform would appear to have issued. Keys SHOULD be held in a hardware or managed key service, and rotated at least yearly (§13.4).

16. Schemas and conformance

The following, in the specification repository, are part of this draft:

A Host Platform claims a level only if its responses validate against the schemas and pass tools/conformance.py for that level. Conformance tests for Levels 2 and 3 are an open topic (Appendix C).

17. References

Normative

• [POPPY] Personal Agent Protocol, draft 0.2. https://personalagentprotocol.org/docs/introduction
• [POPPY-OPS] Personal Agent Protocol, Operations extension, version 1. https://personalagentprotocol.org/docs/0.2/extensions/operations
• [RFC2119] Key words for use in RFCs to Indicate Requirement Levels.
• [RFC8174] Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words.
• [RFC7515] JSON Web Signature. [RFC7517] JSON Web Key. [RFC7518] JSON Web Algorithms. [RFC8037] CFRG Elliptic Curve Signatures in JOSE. [RFC8785] JSON Canonicalization Scheme.
• [RFC3339] Date and Time on the Internet. [ISO4217] Currency codes. [IANA-TZ] Time Zone Database.
• [JSON-SCHEMA] JSON Schema 2020-12. [OPENAPI] OpenAPI Specification 3.1.
• [VC-DATA-MODEL] W3C Verifiable Credentials Data Model 2.0.

Informative

• [SCHEMA] schema.org Accommodation, LodgingBusiness.
• [BCP47] Language tags. [ISO3166] Country codes.

Appendix A. A complete booking, end to end

1. The agent fetches https://stay.livaround.com/.well-known/poppy.json: livstay.org/stays revision 0.2, level 3, and operations version 1.
2. With no token, GET /livstay/v0/homes?area=north-goa&check_in=2026-12-27&check_out=2027-01-03&adults=4&children_ages=7,1 with LivStay-Revision: 0.2.
3. The agent reads three Homes' Facts and tells the traveller why Casa Mira fits, citing facts_version 9.
4. With no token, POST /homes/home_7Qp2/quotes → qt_P8m1, total INR 1,29,500.00, expires in 24 hours. The agent verifies the signature and reconciles the lines. The traveller wants to sleep on it.
5. Next morning, in a signed-out Session, the agent opens an enquiry: "Is the pool fenced? Our youngest is one." Host Rhea answers in 40 minutes, signed.
6. The traveller says book it. The agent signs them in with livstay:book, poppy:read and livstay:share_trip_context.
7. POST /livstay/v0/bookings with qt_P8m1 → 202, operation bk_4Hn9 proposed, calendar held 15 minutes, requirements: ["payment", "identity_verification"].
8. The agent checks the revision against the Quote, shows the summary; the traveller approves.
9. POST /poppy/operations/bk_4Hn9/confirm { "revision": 1, "approved_by": "user" } → in_progress. GET /livstay/v0/bookings/completion/bk_4Hn9 → complete_by in 60 minutes, two pending steps with page URLs.
10. The traveller verifies identity and pays INR 38,850.00 in their browser Session. The operation → succeeded; result.data.livstay carries bkg_4Hn9, the address and a Receipt. The feed shows payment_received with its Receipt, then booked.
11. A week later the feed shows message_waiting. The agent opens the booking conversation and reads Rhea's question about the airport pickup.
12. Twelve days before arrival the feed shows payment_due; on the day, check_in_details; three days after check-out, deposit_released with a Receipt.

Appendix B. How LivAround implements this draft

Informative. LivAround is the reference Host Platform.

Appendix C. Open topics on the path to 1.0

• Conformance for Levels 2 and 3. An executable suite needs a test Personal Agent with a Poppy client identity, sign-in and DPoP. Planned alongside the reference implementation.
• Payments. Adopt Poppy's payment design when it exists (§11).
• Push. Booking events need Poppy push notifications; until then, the event feed with wait.
• Attachments. Receipts and check-in packs as Poppy attachments when defined.
• Multi-home stays. One booking across linked Homes (a villa and its cottage).
• Points and exchange. A member-authenticated extension for swaps and points, if ever.
• Search. Whether GET /homes needs a shared query vocabulary across Host Platforms.
• Directory. How agents find Host Platforms beyond domains they already know.
• Governance. Moving the spec to a neutral home once there are independent implementers.

Appendix D. Changes from draft 0.1

Draft 0.2 is not compatible with 0.1. Both sides now say which they speak (§4.3).

1. Access matches Poppy. Signed-out Poppy tokens carry no scopes, so homes, availability and Quotes are public with no token, and enquiries need a signed-out Session with no scope. livstay:enquire is removed. Levels 0 and 1 need no Poppy Session (§3.3, §5).
2. The agent opens the booking conversation. Poppy conversations are agent-started. Host and Host Platform updates move to a booking event feed (§12.2); Host messages wait for the agent, announced by message_waiting (§12.3).
3. Completion replaces hold extension. Confirmed operations cannot be revised, so payment and identity verification run against a fixed complete_by in a completion record beside the operation (§9.5). Revisions no longer extend holds.
4. Wire format. JSON Schemas, an OpenAPI document, fixtures, a validator and a Level 0–1 conformance runner (§16). Signing is specified: ES256, kid, typ, RFC 8785 payloads, verification steps, rotation and retention (§13.1–§13.4).
5. Revisions. revision in poppy.json, revisions in client metadata, and the LivStay-Revision header (§4.3).
6. Lifecycle. - Each Home has an IANA time_zone. - Money has fixed precision, rounding and reconciliation rules (§2.1). - guests becomes party, with children's ages and pets (§2.2); Terms gain infant and pet rules. - Contact sharing and revocation have endpoints (§12.4). - Trip context is deleted after a failed, cancelled or expired proposal. - Receipts cover payments, refunds, deposits, claims and Host cancellations (§13.3). - tier_not_accepted is removed: tier outcome is reported in terms.livstay.tier, and a Quote made for a higher tier fails with tier_mismatch.