Connect your agent to PropRaven

The flow: discover → preview → pay

1. Discover — read the field catalog to see what exists and how complete it is, per field and per state. Free, no payment.
2. Preview — for a specific parcel, get back the exact dossier price and the multipliers behind it, before you spend anything. Free.
3. Pay — buy the product per call over x402 (a wallet, no account), or on a paid PropRaven subscription. Five products today: the per-parcel dossier, a per-lead lead feed, a per-owner owner intelligence report, a per-parcel comp pack (valuation), and a per-parcel risk score (FEMA-anchored).

The discovery surface is free on purpose: the catalog is the storefront. Agents read data dictionaries, not landing pages.

1. Connect the MCP server

The hosted Model Context Protocol server is at propraven.com/mcp. Bearer auth (Authorization: Bearer pz_…) works in Claude Desktop, Claude Code, Cursor, and Smithery; the claude.ai web connector uses OAuth. Full setup for each client, and all 31 tools, are on the MCP docs page (generated from the live registry).

{
  "mcpServers": {
    "propraven": {
      "url": "https://propraven.com/mcp",
      "headers": { "Authorization": "Bearer pz_your_real_key_here" }
    }
  }
}

The tools that matter for the storefront flow:

2. Discover — the free catalog

Over MCP call get_catalog; over REST hit the same data directly. Every serving column with its measured coverage, grain, tier, honesty flags, and pipeline freshness warts. Filter by state, tier, section, min_coverage, q.

curl "https://api.propraven.com/api/v1/storefront/catalog?state=NC&min_coverage=0.8"

Coverage is measured per field per state: the national average hides local gaps (flood-zone coverage is thin in FL, rich in CA), so check the jurisdiction you care about.

curl "https://api.propraven.com/api/v1/storefront/availability?state=FL&county=086"

3. Preview — the exact price, before you pay

Ask for a specific parcel and get back the value-tiered dossier price and the multipliers behind it. This uses the same math the paid endpoint charges — the previewed price equals what the payer is billed. Over MCP that's check_availability; over REST:

curl "https://api.propraven.com/api/v1/storefront/availability?parcel_id=37:183:0012345"

{
  "mode": "parcel",
  "parcel": { "canonical_id": "37:183:0012345", "state_fips": "37", "county_fips": "183", ... },
  "dossier_quote": {
    "price": { "amount": "12.40", "currency": "USD" },
    "price_usd": 12.4,
    "price_atomic_usdc": "12400000",       // what the x402 402 advertises (USDC, 6dp)
    "asset": "USDC",
    "band": { "key": "multifamily", "label": "...", "range": "..." },
    "breakdown": { "base": 5, "V": 1.7, "R": 1.2, "F": 1.0 },  // BASE x V x R x F, clamped
    "signals": { "assessed_value": 3200000, "populated_fields": 480, "has_deeds": true, "has_permits": true },
    "pay": ["x402"]
  }
}

4. Pay per call with x402

The dossier is a paid product. A wallet-bearing agent pays USDC on Base per call, with no account. Request it with no payment first and you get an HTTP 402 that tells you exactly what to sign:

curl -i "https://api.propraven.com/api/v1/parcels/37:183:0012345/report"
# → HTTP/1.1 402 Payment Required

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "12400000",     // THIS parcel's price, USDC atomic (6dp). Dynamic.
      "resource": "https://api.propraven.com/api/v1/parcels/37:183:0012345/report",
      "payTo": "0x…",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC on Base
      "maxTimeoutSeconds": 120,
      "extra": { "name": "USDC", "version": "2" }              // USDC EIP-712 domain
    }
  ],
  "error": "Payment required for the parcel dossier."
}

Sign an EIP-3009 transferWithAuthorization for exactly maxAmountRequired, base64-encode the x402 PaymentPayload, put it in the X-PAYMENT header, and retry. On a good build you get 200 with the dossier and the on-chain settlement receipt in X-PAYMENT-RESPONSE. A failed build is never charged.

curl -i "https://api.propraven.com/api/v1/parcels/37:183:0012345/report" \
  -H "X-PAYMENT: <base64 signed x402 PaymentPayload>"
# → HTTP/1.1 200 OK
# → X-PAYMENT-RESPONSE: <base64 on-chain settlement receipt>
# → { "parcel": {…}, "fields": [ { "name": …, "value": …, "source": …, "as_of": …, "confidence": … } ], "sections": { "deeds": {…}, "comps": {…}, "permits": {…} }, "meta": {…} }

Most x402 client libraries do the sign-and-retry for you: point the wrapper at the URL with a funded wallet and it handles the 402. PropRaven relays verification and settlement through an x402 facilitator — it never holds your key.

Prefer an account? Authenticate with a pz_ key on a paid PropRaven subscription and the dossier is served on your invoice instead. Being merely authenticated is not enough — a free-tier or self-service key with no paid plan gets the same 402.

5. Lead feeds — buy the answer, not the database

The dossier answers “tell me everything about this parcel.” A lead feed answers the question an acquisitions agent actually asks — “give me the qualified targets matching this signal, here” — and is priced per lead. Same 402 flow, same wallet, no account.

Preview first: the preview is free and returns the exact count, the exact price, and three masked sample leads (APN truncated, house number stripped, owner withheld) — enough to judge the set, not enough to work it.

curl "https://api.propraven.com/api/v1/leads/find?signal=distressed&state=NC&county=183&limit=50&preview=true"

{
  "signal": "distressed",
  "geo": { "state": "NC", "state_fips": "37", "county_fips": "37183", "limit": 50 },
  "count": 50,                              // leads that WILL be delivered = min(matching, limit)
  "quote": {
    "per_lead": { "amount": "0.4750", "currency": "USD" },
    "total": { "amount": "20.00", "currency": "USD" },
    "total_atomic_usdc": "20000000",        // what the x402 402 advertises
    "tier": "mid",
    "breakdown": { "base_per_lead": 0.25, "S": 1.9, "V": 1, "capped": true }
  },
  "preview": true,
  "sample": [ { "canonical_id": "37:183:•••", "address": "••• MAPLE ST", "owner_name": null, "lead_score": 82, "masked": true } ]
}

Drop preview=true and the same URL becomes the paid resource: a 402 carrying that exact total, or — with an X-PAYMENT header — the full unmasked set with the settlement receipt in X-PAYMENT-RESPONSE. Over MCP it is one tool, find_leads.

per_lead = clamp( $0.25 × S × V , $0.05 , $1.00 )
total    = min( count × per_lead , $20 )

  S  signal strength   how close the cohort sits to a transaction:
                       absentee 1 · long_hold 1.1 · entity_owned 1.15 · portfolio_owner 1.25
                       · high_land_ratio 1.4 · flip 1.6 · distressed 1.9
  V  asset-value tier  median assessed value of the delivered set:
                       low 0.7 · mid 1 · high 1.5 · premium 2.2

You pay for the leads delivered — min(matching rows, limit, default 25, max 200). An empty result is returned free and never charged for. state is required: every pull is pruned to one state.

Honest about what it is: distressed is derived from assessment data (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 — PropRaven does not collect those yet, and will say so rather than sell a proxy under the wrong name.

Pricing model

The dossier is value-tiered per parcel, and the price is always shown before you pay (step 3). The formula is auditable (the lead-feed formula is in step 5):

price = clamp( $5 × V × R × F , $2 , $20 )

  V  asset value      log-scaled on assessed value (a $50k lot and a $50M office
                      are not worth the same provenance)
  R  data richness    how much we actually have on this parcel (populated fields,
                      plus real deed/permit sub-tables)
  F  freshness        1.0× cached (base) — a guaranteed-fresh re-collect is a premium dial

The floor is $2 and the cap is $20. The GeoJSON parcel boundary is a separately-priced add-on the base dossier omits. The preview endpoint returns the full breakdown so an agent can see why a parcel costs what it costs.

Get an API key

A free pz_ key covers MCP bearer auth and the REST API, including the free discovery surface. Create a key → You do not need a key to pay via x402 — a funded wallet is enough.

Resources

• · MCP server + full tool reference
• · OpenAPI 3.1 spec — storefront + x402 dossier surface
• · llms.txt · llms-full.txt
• · x402 protocol · API docs