# PropRaven — full agent reference

> Agent-native US property and parcel intelligence: ~191M distinct parcels (110M mapped), a 620-field catalog (615 sellable) with honest per-field coverage and freshness, provenance-first dossiers. Reachable over a hosted MCP server and a pay-per-call x402 endpoint. This file expands on https://propraven.com/llms.txt with the MCP tool list, the REST endpoint reference, and the x402 request/response shapes.

Canonical, always-current sources (prefer these over any static list below):
- MCP tool list: call `tools/list` on https://propraven.com/mcp , or read https://propraven.com/docs/mcp (generated from the live registry).
- REST surface: https://propraven.com/openapi.json (OpenAPI 3.1). Also served at https://api.propraven.com/openapi.json .

## Authentication

- API key: a `pz_` key, passed as `Authorization: Bearer pz_...`. Works for the REST API and for MCP bearer clients (Claude Desktop, Claude Code, Cursor, Smithery). Get one free: https://propraven.com/settings/api-keys
- OAuth: the claude.ai web connector uses authorization-code + PKCE (no header field in that UI). Discovery (RFC 9728): https://propraven.com/.well-known/oauth-protected-resource/mcp (resource `https://propraven.com/mcp`; the root .../oauth-protected-resource serves the same document) and https://propraven.com/.well-known/oauth-authorization-server
- x402: no account. A wallet-bearing agent pays per call (see the x402 section).

## MCP server

- Endpoint: https://propraven.com/mcp (canonical; also answers at https://api.propraven.com/mcp).
- Transport: JSON-RPC 2.0 (Streamable HTTP / SSE). Quick check:
  curl -X POST https://propraven.com/mcp -H "Authorization: Bearer pz_..." -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
- Client config (Claude Desktop / Cursor), header auth:
  { "mcpServers": { "propraven": { "url": "https://propraven.com/mcp", "headers": { "Authorization": "Bearer pz_your_key" } } } }
- Local stdio package (optional): `npm install -g @propraven/mcp` then run `propraven-mcp` with `PROPRAVEN_API_KEY`.

### Tools (31; snapshot — the live list is authoritative)

Every tool is read-only. Two discovery tools are FREE and unmetered at the MCP boundary; the `buy_*` tools and `find_leads` are the paid purchase products. The rest are metered against your plan.

Discovery (FREE):
- get_catalog — Browse the data catalog: the field dictionary an agent reads to decide whether PropRaven has what it needs, with per-field coverage/freshness.
- check_availability — Try-before-buy: what a dossier would contain AND what it costs for a jurisdiction or a specific parcel, before paying.

Purchase (PAID):
- buy_dossier — Buy the per-parcel dossier: one provenance-first payload with every populated field. Returns either a receipt or a payment-required instruction (pay via x402).
- find_leads — Buy a LEAD FEED: the qualified target list for one signal in one state (absentee | long_hold | entity_owned | portfolio_owner | high_land_ratio | flip | distressed), priced PER LEAD. Call with preview=true first — the preview is FREE and returns the exact count, the exact price and three masked sample leads. Returns either the delivered leads or a payment-required instruction (pay via x402).
- buy_owner_report — Buy the OWNER INTELLIGENCE REPORT: pierce one owner name (or a public company `ticker`) to its FULL property portfolio nationwide, priced PER RESOLUTION. Answers "who really owns this, and what else do they own?" Returns the full deduped portfolio with a per-state breakdown, total assessed value, entity type, and each property. Call with preview=true first — the preview is FREE and returns the parcel count, total value, states spanned, the exact price and three masked sample properties. Returns either the delivered report or a payment-required instruction (pay via x402).
- buy_comp_pack — Buy the COMP PACK: 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 IQR range + method/basis, and the full comps it was built from (reconstructable, not a black-box AVM). Call with preview=true first — FREE: the subject summary, comp count, exact price and three masked comps. Returns either the delivered pack or a payment-required instruction (pay via x402).
- buy_risk_score — Buy the RISK SCORE: a multi-hazard risk assessment for one parcel, priced PER ASSESSMENT (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/seismic/windstorm/wildfire/air-quality/crime breakdown. Call with preview=true first — FREE: which hazard layers resolved and the exact price. Returns either the delivered assessment or a payment-required instruction (pay via x402).

Parcels & owners:
- parcel_lookup — Resolve one parcel by identifier (state_fips:county_fips:parcel_id), street address, or APN.
- parcel_lookup_batch — Resolve up to 25 parcel queries in one call.
- parcel_search — Filter parcels by geography AND attributes.
- parcel_compare — Assemble a granular record for 2–25 parcels and rank them against criteria.
- parcel_report — Full property report for one parcel (identity, owner, valuation, and more).
- owner_pierce — Resolve an owner name or entity to its full property portfolio.
- occupant_lookup — Commercial occupants (businesses) matched to one parcel.
- valuation_estimate — Estimated market value, assessed value, and last sale price for a parcel.
- hazard_score — Composite hazard score (flood/FEMA NFIP, wildfire, seismic, windstorm, ...).
- permits_history — Building/construction/demolition permit timeline for a parcel.
- sales_history — Deed / transaction timeline for a parcel.
- comps — Comparable recent sales for a subject parcel, from the precomputed comp set.
- get_freshness — How current PropRaven's served data is.

Deals & market:
- deals_absentee — Absentee-owner parcels (mailing address differs from property) in a county/state.
- deals_flips — Recent flips, or (view=flippers) the top flippers.
- deals_contractors — Contractors ranked by permit activity.
- deals_lenders — Lenders ranked by mortgage count.
- deals_entities — LLC/CORP/TRUST-owned parcels, or (top=true) the largest entities.
- deals_long_hold — Long-held parcels (tired-landlord / off-market leads).
- deals_high_land_ratio — Land-dominant parcels (teardown / redevelopment candidates).
- deals_portfolio_owners — Owners holding multiple properties.
- market_coverage — Where PropRaven has parcel coverage (national or per-state).
- market_snapshot — Market-intelligence snapshot for one geography (demographics, jobs, lending).
- cmbs_exposure — CMBS debt exposure by owner or parcel.

## REST endpoints (agent surface)

Base: https://api.propraven.com (also https://propraven.com). Full spec: /openapi.json

Free discovery (no payment; authenticated callers unmetered/uncapped, anonymous served and IP-throttled):
- GET /api/v1/storefront/catalog — the sealed field catalog. Filters: state, tier, section, grain, min_coverage, red_cells, q, include, fields.
- GET /api/v1/storefront/availability?state=NC[&county=183] — per-jurisdiction coverage + base quote.
- GET /api/v1/storefront/availability?parcel_id=37:183:0012345 — the exact value-tiered dossier price for one parcel, with the V/R/F breakdown and the signals it was derived from. Uses the same math the paid endpoint charges.
- GET /api/v1/leads/find?signal=distressed&state=NC&preview=true — the FREE lead-feed preview: how many qualified leads exist for that signal + geography, the exact per-lead and total price, and up to three MASKED sample leads (APN truncated to state:county, house number stripped, owner name withheld). Same math the paid call charges.

Paid, per-call dossier:
- GET /api/v1/parcels/{id}/report — the provenance-first dossier. Value-tiered price = clamp($5 × V(asset value) × R(data richness) × F(freshness), $2, $20). Pay via x402, or on a paid PropRaven subscription. See below.

Paid, per-LEAD lead feeds:
- GET /api/v1/leads/find?signal=…&state=…[&county=&zip=&value_min=&value_max=&limit=] — the qualified target list, delivered as lead records. Required: `signal` (absentee | long_hold | entity_owned | portfolio_owner | high_land_ratio | flip | distressed) and `state` (2-letter, every pull is pruned to one state). `limit` defaults to 25, max 200. `zip` is supported only on long_hold and entity_owned.
  - Price: per_lead = clamp($0.25 × S(signal strength) × V(asset-value tier), $0.05, $1.00); total = min(count × per_lead, $20). S runs absentee 1.0 → long_hold 1.1 → entity_owned 1.15 → portfolio_owner 1.25 → high_land_ratio 1.4 → flip 1.6 → distressed 1.9. V is the median assessed value's tier (low 0.7 / mid 1.0 / high 1.5 / premium 2.2).
  - You pay for leads DELIVERED — min(matching rows, limit). An empty result is returned free and never charged for.
  - Each lead: { canonical_id (state:county:APN), address, city, state, zip, owner_name, assessed_value, <that signal's strength fields>, lead_score (1–100, deterministic), provenance { as_of, source } }.
  - `distressed` is an ASSESSMENT-DERIVED cohort (a structure on the books assessed at a nominal value, on land that carries real value). It is NOT a pre-foreclosure, tax-lien or lis-pendens feed.

Paid, per-OWNER intelligence report:
- GET /api/v1/owners/{name}/report[?ticker=WFC][&state=NC][&limit=100&offset=0] — pierce one owner (or a public ticker's curated entity family) to its full, deduped national portfolio. Required: the URL-encoded owner `name` in the path. Optional: `ticker` (a listed company's entity family wins over the name), `state` (2-letter USPS or 2-digit FIPS, scopes the pierce), `limit` (properties per page, default 100, max 500 — the summary always covers the FULL portfolio) and `offset`.
  - Price: per resolution = clamp($1.75 × P(portfolio size) × V(portfolio value), $0.25, $20). P is log-scaled on the distinct parcel count the pierce uncovers (the dominant axis — the work an agent cannot do itself); V is log-scaled on the summed assessed value. Missing value floors V, never raises the price.
  - You pay for the RESOLUTION. A pierce that uncovers zero parcels is returned free with a $0 quote and never charged.
  - Payload: { owner { query_name, ticker, entity_type, resolved_variants }, summary { count, total_assessed_value, total_acreage, states, by_state[] }, properties[] (each: canonical_id, address, valuation, lot/building, last sale, property_type), provenance { as_of, source }, meta { catalog_version, catalog_seal } }.
  - `preview=true` returns the summary, the exact price and up to three MASKED sample properties (APN truncated to state:county, house number stripped) — free, no key.

Paid, per-parcel COMP PACK (the valuation grain):
- GET /api/v1/parcels/{id}/comp-pack[?n=8][&radius=2] — a subject valuation INDICATED BY comparable sales, wrapped with the comps that prove it. `n` = how many comps back the pack (default 8, max 50); `radius` = optional post-filter on precomputed distance_miles.
  - Price: per pack = clamp($2 × V(subject assessed value) × Q(comp support), $1, $20). Q ramps on the comp count with a small bonus for high median similarity. A subject with zero precomputed comps has no evidence to support a number and is returned free, never charged.
  - Payload: { subject { canonical_id, assessed/market value, building_sqft, property_type, last sale }, valuation { indicated_value, low, high (IQR of comp prices), method (price_per_sqft | median_sale_price), basis { comp_count, median_similarity, median_comp_price, median_price_per_sqft, subject_sqft } }, comps[] (the evidence), provenance, meta }. The indicated value is reconstructable from the comps — never a black-box AVM.
  - `preview=true` returns the subject summary, the comp count, the exact price and up to three MASKED comps (parcel/APN withheld, sale price rounded, date to the year); the indicated valuation is withheld — free, no key.

Paid, per-parcel RISK SCORE (the underwriting grain):
- GET /api/v1/parcels/{id}/risk-score — a multi-hazard risk assessment anchored on FEMA's National Risk Index composite.
  - Price: per assessment = clamp($0.60 × V(asset value) × C(hazard coverage), $0.20, $20). C ramps on how many independent hazard layers resolved (NRI composite, flood, seismic, windstorm, wildfire, air quality, crime). A parcel with zero layers is returned free, never charged.
  - Payload: { subject, hazard_layers[], assessment { composite { nri_risk_score (0-100), nri_risk_rating, nri_wildfire_rating, climate_risk_tier/label }, flood { flood_zone, is_sfha, flood_risk_score }, hazards { seismic, windstorm, wildfire, air_quality, crime } }, provenance, meta }. The headline is FEMA's own methodology.
  - `preview=true` returns the subject, WHICH hazard layers resolved, and the exact price; the NRI score + breakdown are withheld — free, no key.

## x402 pay-per-call flow

All five paid products — the per-parcel dossier, the per-lead feed, the per-owner report, the per-parcel comp pack, and the per-parcel risk score — use the SAME flow. An agent with a wallet pays USDC on Base per call, with no account:

1. GET the resource with no payment (/api/v1/parcels/{id}/report, or /api/v1/leads/find?signal=…&state=…).
2. Receive HTTP 402 with a JSON body: { "x402Version": 1, "accepts": [ { "scheme": "exact", "network": "base"|"base-sepolia", "maxAmountRequired": "<this parcel's price in USDC atomic units, 6 decimals>", "resource": "<the URL>", "payTo": "<wallet>", "asset": "<USDC contract>", "maxTimeoutSeconds": 120, "extra": { "name": "USDC", "version": "2" } } ], "error": "..." }
   - maxAmountRequired is DYNAMIC (never a flat price). Dossier: per parcel, 2000000 = the $2 floor, 5000000 = $5.00, 20000000 = the $20 cap. Lead feed: count × per-lead, capped at 20000000 ($20). Owner report: per resolution (portfolio size × value), 250000 = the $0.25 floor, capped at 20000000 ($20). Comp pack: per pack (subject value × comp support), 1000000 = the $1 floor, capped at 20000000 ($20). Risk score: per assessment (asset value × hazard coverage), 200000 = the $0.20 floor, capped at 20000000 ($20).
   - Preview this exact amount for free first: GET /api/v1/storefront/availability?parcel_id={id} (dossier_quote.price_atomic_usdc), or GET /api/v1/leads/find?…&preview=true (quote.total_atomic_usdc).
3. Sign an EIP-3009 transferWithAuthorization for exactly maxAmountRequired, base64-encode the x402 PaymentPayload, and set it as the `X-PAYMENT` request header. Retry the GET.
4. On a successful build you receive HTTP 200 with the payload (the dossier, or the leads) and the base64 on-chain settlement receipt in the `X-PAYMENT-RESPONSE` response header. A failed build is never charged, and one payment yields exactly one delivery (the (payer, nonce) pair is claimed in a settlement ledger before the payload is assembled).

Alternative to x402: authenticate with a `pz_` key that holds a paid PropRaven subscription — the product is served on the subscription invoice. A free-tier or self-service key with no paid plan receives the 402 (pay via x402).

Dossier payload shape (see ParcelDossier in the OpenAPI spec):
- parcel: identity (canonical_id, state_fips, county_fips, parcel_id, address).
- fields[]: every populated field with { name, value, source, as_of, confidence, confidence_basis, national_coverage, state_coverage, tier, grain, section, flags, catalogued }.
- sections: { deeds, comps, permits } — each { relation, as_of, status, row_count, rows[] }.
- boundary: the GeoJSON add-on (omitted from the base payload; separately priced).
- meta: catalog_version, catalog_seal, generated_at, field_count, provenance_note, entitlement, price.

## Honest-coverage philosophy

Coverage is measured per field per state and shipped with the warts. The national average hides local gaps, so the catalog and availability endpoints expose per-jurisdiction and per-parcel fill before any spend, and non-ok freshness probes are flagged in-band (`warts`) rather than smoothed over. Every dossier value carries its source, date, and field-level coverage so an agent can cite, weigh, and date what it acts on.

## More

- Connect-your-agent guide: https://propraven.com/docs/agents
- MCP docs: https://propraven.com/docs/mcp
- API docs: https://propraven.com/docs/v1
- Terms: https://propraven.com/terms