Protocol Documentation

The HomeSelf Protocol

Not a portal. A canonical registry for Verified Property Records.

Interactive AnswerPack Viewer

Every property generates an AnswerPack - a structured JSON document optimized for LLM context windows. Expand sections to explore.

f47ac10b.answerpack.json

{
  "hsp_protocol_version": "1.1",
  "hsp_internal_version": "2.1",
  "tier": "standard"
}

{
  "trust_score": 0.91,
  "trust_level": "platinum",
  "verification_level": "document_verified",
  "verified_documents_count": 3
}

The HomeSelf Protocol defines how properties become structured, verifiable records that AI systems can trust.

Canonical Definition

What is a VPR?

Verified Property Record (VPR) is a structured, machine-readable representation of a real-world property, designed to be discoverable, interpretable, and analyzable by AI systems.

This structure is demonstrated in a live example VPR.

Human Layer

A VPR IS:

A structured representation of a property
Identified by a unique, immutable ID
Computed from owner inputs, AI analysis, and data consistency checks
Published to a public registry queryable by AI systems

A VPR IS NOT:

A legal ownership certificate
A guarantee of transaction safety
An advertisement or premium placement
A replacement for legal due diligence

AI Layer

VPRs are machine-readable records that power:

AnswerPack

Structured JSON for LLM context windows

Registry Query

Public API for property discovery

AI Matching

Semantic property-to-seeker routing

Role of HomeSelf

HomeSelf provides the reference human–AI interface and the public registry where VPRs are created, validated, versioned, and made discoverable with trust signals.

See a canonical example of a Verified Property Record →

Supported Property Types (V1)

V1 PRIMARY

Residential Unit

Residential UnitDescription

apartment

flat, condo

studio

monolocale

loft

—

penthouse

attico

house

detached, townhouse

villa

—

townhouse

—

duplex

—

triplex

—

room

private room in shared property

V1 SUPPORTED

Commercial Space

Commercial SpaceDescription

commercial

generic commercial space

office

business premises

retail

shop, store

V1 SUPPORTED

Industrial Space

Industrial SpaceDescription

warehouse

storage facility

V1 SUPPORTED

Land

LandDescription

land

generic land

vacant_land

building plot

plot

parcel

V1 SUPPORTED

Building

BuildingDescription

building

multi-unit building

V1 SUPPORTED

Ancillary Space

Ancillary SpaceDescription

garage

parking space

parking

parking spot

storage

self-storage unit

V1 SUPPORTED

Hospitality Unit

Hospitality UnitDescription

hotel

—

bed_and_breakfast

B&B

V1 SUPPORTED

Special Asset

Special AssetDescription

other

custom type

Note: Property type determines registry classification and query behavior. Room searches return only room listings; all other searches exclude rooms (entire_property bucket).

Portals vs Protocol

HomeSelf isn't another property portal. It works differently by design.

Traditional Portals	HomeSelf Protocol
Listings are ads	Records are protocol entries
Data optimized for humans	Data optimized for AI + humans
Visibility is paid	Discovery is semantic
Each portal has its own copy	One canonical record
Agents mediate access	Direct owner ↔ seeker
SEO tricks	Registry queries
Platform owns data	Owner controls record

Key Insight: Portals are walled gardens that monetize attention. HomeSelf is a public registry that makes property data universally accessible to AI systems.

VPR Lifecycle

Draft

Private construction — only you can see and edit

Active

Public registry — discoverable by search and AI systems

Paused

Temporarily hidden — data preserved, not discoverable

Archived

Historical record — not deleted, preserved for reference

Property Intents

Code	Intent	Description
`sell`	Selling	Property for sale
`rent_long`	Long-term Rental	12+ month leases
`rent_short`	Short-term / Hospitality	Vacation, Airbnb-style
`room`	Shared Living	Private room in shared property
`invest`	Yield-focused	Investment / rental income
`relocate`	Cross-border	International / relocation
`develop`	Land / Projects	Development opportunities

Note: Intent is set when creating a VPR and can be changed. Search filters often use intent to match properties to specific use cases (e.g., filtering "rent_long" for annual rentals vs "rent_short" for vacation stays).

Trust Score Explained

Every listing has a computed Trust Score (0.0 - 1.0) based on verifiable data. No fake reviews, no paid rankings.

Completeness40%

How many fields are filled (title, description, photos, price, etc.)

Documents30%

Document consistency (cadastral, energy certificate, ownership)

Photos20%

AI-analyzed photo quality and authenticity

Freshness10%

How recently the listing was updated

API Reference

Public endpoints for searching properties and accessing the registry. All data is read-only and optimized for LLM consumption.

POST/api/seeker/search

Natural language property search

Request

{
  "query": "2-bedroom apartment in Milan under 300k",
  "limit": 10
}

Response

{
  "results": [
    {
      "id": "uuid",
      "title": "Bilocale luminoso",
      "trust_score": 0.87,
      "price": 250000
    }
  ],
  "total": 42
}

cURL Example

curl -X POST https://homeself.ai/api/seeker/search \
  -H "Content-Type: application/json" \
  -d '{"query":"2-bedroom apartment in Milan under 300k","limit":10}'

Protocol Origin

The Verified Property Record (VPR) concept was introduced by Marco Patrone as part of the HomeSelf Protocol.

AI Discovery Surface

Standard endpoints that enable AI systems to discover and consume property data without prior knowledge of HomeSelf.

Endpoint	Description
`/.well-known/ai.json`	AI-Plugin discovery (OpenAI/Anthropic compatible)
`/.well-known/homeself/registry.json`	Paginated index of all active VPRs
`/api/property/{id}.jsonld`	Schema.org JSON-LD for property (SEO indexable)
`/api/property/{id}.answerpack.full.json`	Complete AnswerPack with all computed fields

MCP Tools (Model Context Protocol)

HomeSelf exposes MCP-compatible tools for AI agents using Claude Desktop, Custom GPTs, or any MCP-compatible client.

search_properties

Search listings with natural language

• query (required)

• filters (optional)

• limit (default: 10)

get_property_deep_intel

Get complete AnswerPack for a property

• listing_id (required)

Example: search_properties

{
  "query": "2-bedroom apartment in Milan under 300k",
  "filters": {
    "city": "Milano",
    "max_price": 300000,
    "property_type": "apartment"
  },
  "limit": 10
}

Claude Desktop Configuration

{
  "mcpServers": {
    "homeself": {
      "command": "python",
      "args": ["/path/to/homeself/backend/mcp_server.py"]
    }
  }
}

A2A Negotiation (Handshake)

Agent-to-Agent state machine for property negotiation without human chat. Enables AI agents to negotiate terms autonomously.

State Machine Flow

DISCOVERED

→

MATCHED

→

CONTACTED

→

NEGOTIATING

→

AGREED

→

EXPIRED

→

FAILED

Handshake Endpoints

POST

/api/v1/agent/handshake/start

Initiate negotiation handshake

POST

/api/v1/agent/handshake/respond

Respond to proposal (accept/reject/counter)

POST

/api/v1/agent/handshake/close

End negotiation

GET

/api/v1/agent/negotiation/{id}

Get negotiation status

GET

/api/v1/agent/negotiation/{id}/agreement

Download MoU (if agreed)

Memorandum of Understanding (MoU)

When state reaches AGREED, a machine-readable MoU is generated containing:

{
  "negotiation_id": "uuid",
  "listing_id": "uuid",
  "agreed_at": "2025-01-07T10:00:00Z",
  "parties": {
    "seeker_agent_id": "agent:seeker:abc123",
    "owner_agent_id": "agent:owner:xyz789"
  },
  "terms": {
    "price": 280000,
    "currency": "EUR",
    "closing_date": "2025-03-01",
    "conditions": ["subject_to_inspection"]
  },
  "trust_signals": {
    "property_trust_score": 0.91,
    "verification_level": "document_analyzed"
  }
}

A2A Property Matching

The matching endpoint powers AI agents to find properties that satisfy seeker constraints.

Request Payload

{
  "query": "2-bedroom in Milan under 300k",
  "budget_max": 300000,
  "city": "Milano",
  "property_type": "apartment",
  "min_bedrooms": 2,
  "limit": 10
}

Compatibility Factors

Budget alignment (price within range)
Property type match
Rooms/bedrooms constraints
Surface area requirements
Feature filters (balcony, parking, etc.)
Trust score threshold (0.5+)

Example Response

{
  "success": true,
  "matches": [
    {
      "listing_id": "uuid",
      "title": "Modern 2-Bedroom Apartment",
      "compatibility_score": 92,
      "reasoning": "Matches all criteria: 2 beds, €280k, Milano",
      "trust_score": 0.87,
      "next_questions": ["Is balcony important?", "Need parking?"]
    }
  ],
  "total_found": 42
}