# PropRaven

> Agent-native US property and parcel intelligence. ~191M distinct parcels (110M mapped) across all 50 states, described by a 620-column data catalog that publishes measured per-field coverage — the gaps included, not hidden. 44 columns are rebuilt every epoch; most of the rest come from an April 2026 reference export, and per-field source dates are not yet recorded. Reachable by AI agents through a hosted MCP server and a pay-per-call x402 endpoint that needs no account for parcel data. People data (owner names, owner mailing addresses, lead lists, owner-name lookups) always requires an account; payment alone is not one.

PropRaven is built to be read and paid by machines, not just people. An agent can discover exactly what data exists and how complete it is (free), preview the exact price of a specific parcel's dossier (free), then either call typed tools over MCP or pay per call with a crypto wallet over HTTP 402 — no contract, and no signup for parcel data (a free account unlocks people data).

Two honest numbers to calibrate on: coverage is measured per field per state and shipped with the warts. The national average hides local gaps (e.g. flood-zone coverage is thin in Florida and rich in California), so every discovery surface lets you check the specific jurisdiction or parcel before you spend anything.

## Start here

- [Real estate MCP server](https://propraven.com/real-estate-mcp-server): What the hosted MCP server does for AI agents, how to connect, and how the tools are grouped.
- [Connect your agent](https://propraven.com/docs/agents): The one-page guide — connect the MCP server, run the discover → preview → pay flow, and read a concrete x402 walkthrough with the 402 shape and pricing model.
- [MCP server docs](https://propraven.com/docs/mcp): How to connect the hosted MCP server (Claude, Grok, Cursor, ChatGPT, any MCP client), auth, and the full, always-current tool list (generated from the live registry).
- [Authentication guide](https://propraven.com/auth.md): How an agent authenticates today: x402 pay-per-call (no account), API keys, and the MCP OAuth connector, with endpoints, limits and revocation. Agent self-registration is not available.
- [OpenAPI spec](https://propraven.com/openapi.json): The complete REST surface, including the storefront endpoints and the x402 dossier flow. Valid OpenAPI 3.1.

## Connect over MCP

- [Hosted MCP endpoint](https://propraven.com/mcp): The Model Context Protocol server. Bearer auth (`Authorization: Bearer pz_...`) for Claude Desktop / Claude Code / Cursor / Smithery; OAuth 2.1 (authorization_code + PKCE S256, rotating refresh_token, dynamic client registration) for the Claude, Grok and Cursor connectors, Codex, and any MCP client with an https, loopback or native-app redirect URI. OAuth details: https://propraven.com/docs/mcp#oauth . Three tools — the discovery tools `get_catalog` and `check_availability`, and the entitlement check `get_account` — are FREE and unmetered. The optional npm stdio package `@propraven/mcp` exposes only 8 tools (parcel_lookup, parcel_search, parcel_compare, owner_pierce, hazard_score, valuation_estimate, permits_history, sales_history); the hosted endpoint serves the full set.
- [Get an API key](https://propraven.com/settings/api-keys): Free `pz_` key for MCP bearer auth and the REST API.

## Free discovery (no payment, machine-readable)

- [Data catalog](https://propraven.com/api/v1/storefront/catalog): The field dictionary. Every serving column with its measured national (and optional per-state) coverage, grain, tier, honesty flags, and pipeline freshness warts. Filter by `state`, `tier`, `section`, `grain`, `min_coverage`, `q`. This is the storefront — agents read data dictionaries, not landing pages.
- [Availability preview](https://propraven.com/api/v1/storefront/availability): Try-before-buy. Pass `?state=NC` (optionally `&county=183`) for per-jurisdiction coverage, or `?parcel_id=37:119:11906402` for the exact value-tiered dossier price of one parcel — with the V/R/F breakdown — computed by the same math the paid endpoint charges.

## Pay per call with x402 (no account for parcel data — people data needs a free account)

People data — owner names, owner mailing addresses, entity principals, deed and sale party names — is delivered to PropRaven ACCOUNTS (an API key `Authorization: Bearer pz_...`, an MCP OAuth token or a signed-in session) and to PAID calls on the paid products: the parcel dossier, lead feeds, fact verification (`owner_name`), tax status and watch polls deliver it to a wallet with no account once its x402 payment SETTLES or its `X-CREDIT-TOKEN` debit succeeds — never before. An unpaid caller without an account gets HTTP 401 `code: "account_required"` (or the 402 quote) and no people data. Owner-name lookups (the owner report and every /api/v1/owners/* route), owner cards and list exports still require an account. A free key takes a minute: https://propraven.com/settings/api-keys

- [Parcel dossier](https://propraven.com/api/v1/parcels/{id}/report): The paid, provenance-first dossier — every populated field wrapped with its receipts (value, source, as_of, confidence, coverage tier), plus the real deeds / comparable-sales / permits sub-tables. Value-tiered price = clamp($5 × asset-value × data-richness × freshness, $2, $20). Flow: GET with no payment → HTTP 402 whose `accepts[0].maxAmountRequired` carries this parcel's exact price (USDC atomic units on Base); sign an EIP-3009 payment, base64 it into the `X-PAYMENT` header, and retry; the dossier returns with the on-chain settlement receipt in `X-PAYMENT-RESPONSE`. Preview the price for free first via the availability endpoint above. Bought with a wallet alone, the dossier's people fields (owner name, mailing address, deed parties) are withheld and marked, and not priced; send your API key with the payment to receive them.

- [Lead feeds](https://propraven.com/api/v1/leads/find): The second paid product — a buyable qualified target list, priced PER LEAD. Pass `?signal=distressed&state=NC` (signals: absentee, long_hold, entity_owned, portfolio_owner, high_land_ratio, flip, distressed) for leads carrying canonical_id, owner, assessed value, that signal's strength fields, a deterministic lead_score and provenance. Price = min(count × clamp($0.25 × signal-strength × asset-value-tier, $0.05, $1.00), $20); you pay only for leads delivered, and an empty result is free. Add `&preview=true` for a FREE preview (no account needed): the exact count, the exact price, and three masked sample leads. ACCOUNT REQUIRED for delivery: a lead is an owner's name and mailing address, so a paid pull needs your API key (or a signed-in session) on every rail — x402 (`X-PAYMENT` sent WITH `Authorization: Bearer pz_...`), prepaid credits, or a paid plan (included). A wallet alone gets HTTP 401 `code: "account_required"` before the payment is verified. Each delivered lead carries `owner_contact` — the owner's best mailing address, read from ONE address family of the record with its ZIP, flagged `mail_ready`; add `&mail_ready=true` to keep only parcels with a complete mailing address (add `county` in large states: a pull too broad to finish returns 503 `code: "lead_read_timeout"`, free). Same 402 flow as the dossier once authenticated. Absentee owner lists, with that free preview, are at https://propraven.com/absentee-owner-list.

- [Owner intelligence report](https://propraven.com/api/v1/owners/{name}/report): The third paid product — like lead-feed delivery, it REQUIRES a PropRaven account (an API key, `Authorization: Bearer pz_...`, or a signed-in session) on every call, including the free preview. Payment alone (x402 or an `X-CREDIT-TOKEN`) is not an account; an anonymous call gets HTTP 401 with `code: "account_required"`. Matches one owner name's realistic owner-of-record spellings (or a public company `?ticker=WFC`'s hand-curated entity list) to the parcels titled under them nationwide, priced PER RESOLUTION. This is spelling matching, not a verified corporate or beneficial-ownership link: every property carries `match_basis` (exact_spelling | variant | ticker_curated) and every match is candidate-level. Returns the matched parcels with a per-state breakdown, total assessed value, entity type, and each property's identity/valuation/sale history. Price = clamp($1.75 × portfolio-size × portfolio-value, $0.25, $20). Add `?preview=true` for a free preview (still with your account): the parcel count, total value, the states spanned, the exact price, and three masked sample properties. Optional `?state=NC` scopes the match. Same 402 flow as the dossier once authenticated.

- [Comp pack](https://propraven.com/api/v1/parcels/{id}/comp-pack): The fourth paid product — a subject valuation INDICATED BY comparable sales, priced PER PACK. Answers "what is this worth, and which sales prove it?" Returns the subject's valuation fields, a transparent comps-derived indicated value (median comp $/sqft × subject sqft, else median comp price) with an interquartile range and its method/basis, and the full comparable sales it was built from — reconstructable, never a black-box AVM. Price = clamp($2 × subject-value × comp-support, $1, $20). Add `?preview=true` for a FREE preview: the subject summary, comp count, the exact price, and three masked comps. Optional `?n=8&radius=2`. Same 402 flow as the dossier.

- [Risk score](https://propraven.com/api/v1/parcels/{id}/risk-score): The fifth paid product — a multi-hazard risk assessment for one parcel, priced PER ASSESSMENT (the cheapest SKU). Answers "what could go wrong with this asset?" Anchored on FEMA's National Risk Index COMPOSITE (nri_risk_score 0–100 + rating — FEMA's own methodology, not an invented weighting), with the flood (zone/SFHA/score), seismic (USGS design values), windstorm (NRI + NOAA storm history), wildfire (USFS ranks), air-quality and crime breakdown that supports it. Price = clamp($0.60 × asset-value × hazard-coverage, $0.20, $20). Add `?preview=true` for a FREE preview: which hazard layers resolved and the exact price (the score + breakdown are withheld). Same 402 flow as the dossier.

## Prepaid credits — the recurring / volume rail (x402-native; people data still needs an account)

- [Fund a credit balance](https://propraven.com/api/v1/storefront/credits/topup): The storefront's SECOND payment rail. GET `?amount=10` and pay $10 once via x402 (same 402 flow) to receive a credit token (`pzc_…`). Present it in an `X-CREDIT-TOKEN` header on any paid endpoint to DRAW DOWN the balance — no per-call signature. This is what makes recurring (watch/alerts) and high-volume (batch) work over x402, with no Coinbase CDP and no Stripe. Add `X-IDEMPOTENCY-KEY` to make a debit safe across retries. Check the balance at [/api/v1/storefront/credits/balance](https://propraven.com/api/v1/storefront/credits/balance) (X-CREDIT-TOKEN header).

- [Watch / alerts](https://propraven.com/api/v1/watch): The recurring product — "tell me when this changes." POST a watch (a `filter` of `{parcel_ids:[...]}` — up to 500 specific parcels, e.g. the leads you just bought, as canonical ids `state_fips:county_fips:parcel_id` (a bare parcel_id is county-scoped: one that names several parcels is refused with 422 and the candidate canonical ids) — or `{state_fips:"37"}` or `{county_fips:"183",state_fips:"37"}` for a whole jurisdiction, plus `event_types` from parcel.sold / parcel.owner_changed / parcel.permit_filed) with your `X-CREDIT-TOKEN`; it reports changes going FORWARD. Then GET `/api/v1/watch/{id}` to poll new matching deeds/permit changes since the watch's cursor — each delivered delta debits your credit balance (per_delta = clamp($0.05 × event-strength, $0.02, $0.20), capped $20/poll). Add `?preview=true` for a free count + price; a poll with no changes is free. Creating/listing/deleting watches is free. Deed parties (grantor / grantee names and addresses) are people data: polled with a credit token and no account, they arrive set to null with a `people_fields` marker — send your API key too to receive them.

- [Verify facts](https://propraven.com/api/v1/verify): The cheapest, highest-volume product — verify one catalogued FACT per (parcel, field) assertion, in a batch. POST `{ lookups: [{ parcel_id: "37:119:11906402", fields: ["is_sfha","owner_occupied","zoning"] }] }` (up to 1000 parcels) or GET `?parcel_id=…&fields=is_sfha,flood_zone`. Sellable fields: is_sfha, flood_zone, flood_risk_score, nri_risk_score/rating, owner_occupied, is_absentee, owner_name, assessed_value, market_value, building_sqft, year_built, property_type, zoning, lot_size_acres, last_sale_date/price, address/city/state/zip. Price = min(count × per_lookup, $20), per_lookup bulk-tiered $0.02→$0.012→$0.006. Pay from a prepaid credit balance (X-CREDIT-TOKEN — one draw for the whole batch) or per call via x402. Verifying `owner_name` is people data and requires an account (an API key or signed-in session); without one, a request that asks for it gets HTTP 401 `code: "account_required"` before the quote. Add `?preview=true` for a free count + price.

## People data (account required)

- [Owner card](https://propraven.com/api/v1/owners/card): The owner of record and how to reach them BY MAIL, for one parcel (`?parcel_id=37:119:12345678`) or one owner name (`?name=`; an individual's name matches in any order — LAST FIRST M / FIRST M LAST — with or without TRUSTEE / ET AL, in any case; a name with more than 1,000 parcels in scope answers `status: "too_broad"` with where it was seen — pass `state`, then `county`). The best mailing address is read from ONE address family of the record with its ZIP, flagged `mail_ready` / `po_box` / `equals_situs`, graded A–D with its source and as-of date; a name card lists the owner's distinct mailing addresses across their parcels. A parcel card also lists `other_addresses`: the addresses of the owner's other parcels, graded A (a record ties them to this owner), B (the same full name plus a corroborating record) or C (the same full name only — "possible, unconfirmed", at most 3, never in a mail-merge by default). Phones appear only where a building permit filed in the current owner's era published one (`phone_status`: published | none_published | not_checked). Account required (401 `account_required` otherwise). On an account without a paid plan each card counts as one lookup against the monthly lookup cap (at the cap: 402 `code: "lookup_cap_reached"`). Over MCP: the `owner_card` tool.
- [List mail-merge export](https://propraven.com/api/v1/cohorts/{id}/export): A CSV of one of your lists, one row per mailing address (only mail-ready addresses become rows). Included on a paid plan; any other account pays $0.10 per row, capped at $20 per export, from credits (`X-CREDIT-TOKEN`) or per call via x402 (`X-PAYMENT`, sent with your key). `?preview=true` returns the row count and price free. Account required.

## Philosophy

- [Honest coverage](https://propraven.com/api/v1/storefront/catalog): PropRaven publishes its warts. Every field carries measured coverage; pipeline freshness is reported in `freshness` and `warts`, and per-field source dates (`source_as_of`) are not yet recorded. Stale or suspect pipelines are flagged in-band rather than smoothed over. An agent should be able to cite, weigh, and date every value it acts on — and to see that a field is thin before it trusts it.

## Optional

- [llms-full.txt](https://propraven.com/llms-full.txt): The fuller reference — the MCP tool list, the REST endpoint reference, and the x402 request/response shapes.