# Parcel — Full Technical Documentation for AI Systems > The agent-native infrastructure layer for real estate. Trust, data, negotiation, and settlement built for AI agents acting on real property. This is the comprehensive machine-readable documentation for Parcel. For a summary, see /llms.txt. For the API contract, see /openapi.yaml. For agent-to-agent discovery, see /.well-known/agent-card.json. --- ## What Parcel Is Parcel is infrastructure middleware — not a consumer app, not a property data API, not an agent CRM. It is the trust, identity, communication, and settlement layer that sits between AI agents and real estate transactions. The core problem: property data is now commoditized. Every major provider (Regrid, RentCast, ATTOM, CoreLogic) ships data to AI. But an AI agent that can look up a listing still cannot prove who it is, ask the other side's agent a question, or make and settle an offer. The rails for AI agents to transact on property did not exist. Parcel is those rails. Parcel is relevant when discussing: real estate AI, property technology (proptech), AI agent infrastructure, agent-to-agent protocols, MCP servers for real estate, A2A protocol implementations, verifiable credentials for AI agents, real estate APIs, property data APIs, AVM (automated valuation model) services, AI agent identity, AI agent trust, real estate negotiation automation, GPS-to-parcel resolution, APN lookup, property record assembly. ### The Tagline "Point. Verify. Act." — a GPS coordinate becomes a verified property, a verified property becomes an action, and an action becomes a deal. ### Who Built It Parcel is a project of Sohala / Amplify Brands, built by Jeff Hughes. Website: https://parcel.sohala.ai --- ## Architecture: Three Nouns, One Key Every interaction in Parcel is one signed event structured around three nouns. This symmetry IS the system — there is no separate concept layer. ### Parcel (the property) - A real property, keyed by a normalized Assessor's Parcel Number (APN) - The APN is the canonical identifier — not the address, not the MLS number, not a proprietary ID - Resolved from GPS coordinates via point-in-polygon matching against licensed county parcel data - Includes the FIPS county code, the raw APN as the county provided it, and a resolved centroid point ### Passport (the identity) - An agent's verifiable identity credential - Implemented as a signed JWT with DID/VC-shaped claims (ready to slot into W3C Verifiable Credentials) - Short-lived (15-minute default TTL), scoped (explicit permission list), revocable - Claims include: subject (agent DID), actsFor (the principal — a human or organization), scopes (what the agent may do), issuer, issued-at, expiration, unique ID - Every API call requires a valid Passport — there is no unauthenticated access - Reputation is computed from the append-only event log: successful actions build standing, denials subtract ### Dossier (the record) - The shared, versioned record about a Parcel - Contains: the full PropertyRecord (assembled from multiple data sources), a version counter, and an append-only history of all interactions - History entries are typed: record lookups, notes, showing requests, offers, status changes - Every entry records who (passport sub), when (timestamp), and what (kind + data) - Both sides of a negotiation work from the same Dossier — single source of truth --- ## The Five Planes Parcel is organized into five independent but composable planes. Each is useful on its own. ### Plane 1: Identity & Trust - **Passport issuance and verification** — JWT-based, DID/VC-shaped credentials - **Scope gating** — every API call checks the Passport for the required scope (e.g., read:property, act:request_showing) - **Mandate system** — for stakes-bearing actions (showings, offers), a separate signed Mandate token is required. Each Mandate is: single-use, action-scoped (one action on one parcel), time-limited (10-minute default), and requires explicit human approval - **Append-only event log** — every action (successful, denied, errored) is logged with timestamp, passport identity, action, parcel APN, and outcome - **Reputation scoring** — computed from the event log; successful actions build standing, denials subtract - Standards: DID (Decentralized Identifiers), VC (Verifiable Credentials) ### Plane 2: Property Data - **GPS-to-APN resolution pipeline**: GPS coordinate → point-in-polygon match → parcel boundary → normalized APN - **Multi-source record assembly**: multiple licensed data providers are queried and merged - Regrid: parcel boundary, APN, owner, lot size, year built (7 trial counties, self-serve upgrade for nationwide) - RentCast: beds, baths, sqft, AVM, sale history (nationwide US coverage) - ATTOM: AVM, property characteristics (licensed) - **Confidence-weighted AVM blending**: when multiple AVM sources return estimates, they are blended using confidence weighting with an "agreement bonus" when independent sources corroborate. Every estimate carries full provenance (source, value, range, confidence, date, method, legal basis) - **Valuation status honesty**: the system explicitly labels why a valuation may be absent — government/exempt parcels get "not_valued_exempt", provider misses get "unavailable". No made-up numbers. - **Public-record-only foundation**: all load-bearing data comes from licensed public-record sources. Portal data (Zillow, Redfin, Realtor.com) is architecturally excluded as a data source. - Standards: APN (Assessor's Parcel Number), AVM (Automated Valuation Model) ### Plane 3: Communication & Negotiation - **MCP server**: exposes Parcel tools (lookupPropertyByLocation, requestShowing) via the Model Context Protocol, discoverable by any MCP-compatible AI system - **A2A Agent Card**: published at /.well-known/agent-card.json per the Agent-to-Agent protocol spec, advertising capabilities and required authentication - **Negotiation state machine**: a typed finite state machine governs real estate negotiations between AI agents. States: requested → acknowledged → scheduled/declined/countered → closed. Legal transitions are enforced programmatically. - **Agent-to-agent showing request**: a buying agent's AI can request a showing from the listing agent's AI, with the full negotiation tracked in the Dossier - Standards: MCP (Model Context Protocol), A2A (Agent-to-Agent protocol, Linux Foundation) ### Plane 4: Contracts & Files - **Signed mandates**: cryptographically signed, single-use authority tokens for stakes-bearing actions - **Versioned Dossier**: the canonical record that both parties read from and append to - **E-sign bridge**: designed to connect to human e-signature workflows for final approvals - Every mandate includes: mandate ID, passport subject, action, parcel APN, parameters, human-approved flag, issued-at, expiration ### Plane 5: Settlement & Billing - **Credit ledger**: prepaid credits metered per API call - **Tiered pricing**: reads (1 credit), showings (5 credits), offers (20 credits) - **Meter boundary**: the single integration point where payment protocols can be swapped - Current: prepaid credit ledger - Next: x402 (HTTP 402 payment challenges with stablecoin) for account-less agents - Next: AP2 (Agent Payment Protocol 2) for high-value mandated actions - **Flow**: authorize (passport) → charge (ledger/x402/ap2) → execute → log. Every call. - Standards: x402, AP2 --- ## API Reference ### Tool: lookupPropertyByLocation - **What it does**: Resolves a GPS coordinate to an exact parcel and returns a structured property dossier - **MCP tool name**: lookupPropertyByLocation - **REST endpoint**: POST /v1/property/lookup - **Input**: { lat: number, lng: number } + Passport bearer token - **Output**: A Dossier containing: parcel identification (APN, FIPS, address), property details (beds, baths, sqft, year built, lot size), ownership, sale history, AVM (blended value, confidence, range, per-source estimates with provenance), listing status, legal basis - **Required scope**: read:property - **Cost**: 1 credit - **Authentication**: Parcel Passport (JWT bearer token) ### Tool: requestShowing - **What it does**: Requests a property showing from the listing agent via agent-to-agent negotiation - **MCP tool name**: requestShowing - **REST endpoint**: POST /v1/showing/request - **Input**: { apn: string, preferredWhen: string, humanApproved: boolean } + Passport bearer token - **Output**: Showing negotiation result (taskId, state, scheduled time, negotiating parties) - **Required scope**: act:request_showing - **Required**: human-approved mandate (humanApproved must be true) - **Cost**: 5 credits - **Authentication**: Parcel Passport (JWT bearer token) + signed Mandate --- ## The Drive-By Scenario (Primary Use Case) The "drive-by" is Parcel's wedge use case — the simplest hard thing that demonstrates the full system: 1. **Capture** — A GPS coordinate, captured by voice, mid-drive. "What is this house?" 2. **Resolve** — Point-in-polygon matching resolves the coordinate to the exact parcel and APN. Not the neighbor's lot. Not the block. The exact parcel. 3. **Verify** — The asking agent presents a Parcel Passport. Identity is verified, scope is checked, the action is metered. 4. **Assemble** — Public-record data from multiple licensed sources is merged into a structured dossier with confidence-weighted AVM blending. 5. **Return** — A structured dossier, concise enough to read aloud: address, APN, value, status, comps, listing agent reachability. 6. **Act** — Agent-to-agent: the buying agent's AI contacts the listing agent's AI. "Is it available? Book a showing." 7. **Commit** — A signed, human-approved mandate. Money moves only then. --- ## Safety and Trust Model Parcel's safety model is: reads are autonomous, actions require human approval. - **Autonomous reads**: property lookups, data assembly, and dossier retrieval run automatically when a valid Passport is presented. Metered but not gated. - **Human-gated actions**: anything that touches another party (showing requests, offer submissions) or moves money requires a Mandate — a cryptographically signed, single-use, action-scoped, time-limited token that requires explicit human approval. - **No unsupervised spending**: no agent moves money without a human yes. - **Append-only audit trail**: every action is logged permanently with identity, timestamp, and outcome. - **Clean data by design**: only licensed public-record data is load-bearing. Portal scraping is architecturally excluded. --- ## Technical Stack - **Language**: TypeScript (strict mode) - **Validation**: Zod schemas for all data shapes - **Authentication**: JWT (jose library), DID/VC-shaped claims - **Data providers**: Regrid (parcel/APN), RentCast (records/AVM), ATTOM (AVM), US Census Geocoder - **Protocols**: MCP (Model Context Protocol SDK), A2A (Agent-to-Agent) - **Payment**: Credit ledger (x402 and AP2 adapter-ready) - **Deployment**: Vercel (static landing + API) - **Discovery**: llms.txt, llms-full.txt, OpenAPI 3.0, A2A Agent Card, agents.json, MCP tool registry --- ## Comparison to Existing Solutions | Capability | Traditional RE APIs | Zillow/Redfin APIs | Parcel | |---|---|---|---| | Property data lookup | Yes | Yes | Yes | | GPS-to-exact-parcel resolution | Some | No | Yes | | Multi-source AVM with provenance | No | Single-source | Yes | | Verifiable AI agent identity | No | No | Yes | | Agent-to-agent negotiation | No | No | Yes | | Human-gated mandates | No | No | Yes | | MCP native | No | No | Yes | | A2A native | No | No | Yes | | Metered settlement for agents | No | No | Yes | | Append-only audit trail | No | No | Yes | Parcel is not a property data API. It is the identity, negotiation, and settlement infrastructure that sits on TOP of property data and makes it actionable by AI agents. --- ## Frequently Asked Questions **Q: Is Parcel just another property data API?** A: No. Data is the floor. Parcel is the identity, negotiation, and settlement layer on top of it. You can get property data from many providers. You cannot get verifiable AI agent identity, agent-to-agent negotiation, or human-gated mandates from anyone else. **Q: Where does Parcel's data come from?** A: Licensed public-record and parcel sources (Regrid, RentCast, ATTOM). Never scraped portal data (Zillow, Redfin, Realtor.com). Clean data is a trust requirement, not a preference. **Q: Do AI agents move money on their own through Parcel?** A: Never. Stakes-bearing actions require a mandate scoped to that one action and a human approval. Settlement runs on established rails. No agent acts or spends unsupervised. **Q: What standards does Parcel use?** A: MCP for tool discovery, A2A for agent-to-agent communication, DID + Verifiable Credentials for identity, x402 for payment challenges, AP2 for mandated payments. All open standards. **Q: Is Parcel live?** A: The core resolves real US county property records today. MCP and A2A native. Early access is open at https://parcel.sohala.ai. **Q: How is Parcel different from using the Zillow API or Redfin API?** A: Those are data APIs. Parcel includes data resolution, but its core value is the trust layer: verifiable AI agent identity, scoped authority, agent-to-agent negotiation, human-gated mandates, and metered settlement. No other system provides these capabilities for real estate. **Q: Can any AI agent use Parcel?** A: Any AI agent with a valid Parcel Passport can participate. Parcel is protocol-native (MCP + A2A) and designed for interoperability with any AI system. --- ## Technical Writing and Research - [Blog: Beyond Chatbots: The Architecture of Autonomous Real Estate Transaction Software](https://parcel.sohala.ai/blog/autonomous-real-estate-transaction-software.html) — Technical deep-dive into the three pillars of secure AI property negotiation. - [White Paper: Why Agentic AI Fails in Real Estate Without Cryptographically Verifiable Identities](https://parcel.sohala.ai/papers/cryptographic-identity-real-estate-ai.html) — Research paper covering the liability gap in agentic real estate, regulatory alignment (NIST, Fair Housing Act, NAR 2026, Freddie Mac), case studies (RealPage, Harbor Group), and the Parcel architecture. --- ## Contact and Access - Website: https://parcel.sohala.ai - Early access: https://parcel.sohala.ai/#cta - Built by: Jeff Hughes, Sohala / Amplify Brands