# PropRaven

> Agent-native US property and parcel intelligence. ~191M distinct parcels (110M mapped) across all 50 states, described by a 620-field data catalog (615 sellable) that publishes its own per-field coverage and freshness — the gaps included, not hidden. Reachable by AI agents through a hosted MCP server and a pay-per-call x402 endpoint that needs no account.

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 signup, no contract.

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

- [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, Cursor, ChatGPT, any MCP client), auth, and the full, always-current tool list (generated from the live registry).
- [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 (authorization-code + PKCE) for the claude.ai web connector. Two discovery tools — `get_catalog` and `check_availability` — are FREE and unmetered.
- [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:183:0012345` 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)

- [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.

- [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: the exact count, the exact price, and three masked sample leads. Same 402 flow as the dossier.

- [Owner intelligence report](https://propraven.com/api/v1/owners/{name}/report): The third paid product — pierce one owner name (or a public company `?ticker=WFC`) to its FULL property portfolio nationwide, priced PER RESOLUTION. Answers "who really owns this, and what else do they own?" Returns every parcel the owner holds 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: the parcel count, total value, the states spanned, the exact price, and three masked sample properties. Optional `?state=NC` scopes the pierce. Same 402 flow as the dossier.

- [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 (no account, x402-native)

- [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 — 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.

- [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:183:0012345", 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. Add `?preview=true` for a free count + price.

## Philosophy

- [Honest coverage](https://propraven.com/api/v1/storefront/catalog): PropRaven publishes its warts. Every field carries measured coverage and freshness; 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.