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), 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 dossier and the lead feed include owner names and mailing addresses for a wallet with no account, returned once the payment settles. The owner report needs an account as well as the payment (send your pz_ key with it); a wallet alone gets HTTP 401 code: account_required.

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; connector UIs such as Claude and Grok sign in with OAuth (with refresh tokens). Full setup for each client, and all 45 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:119:11906402"

{
  "mode": "parcel",
  "parcel": { "canonical_id": "37:119:11906402", "state_fips": "37", "county_fips": "119", ... },
  "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. No account is needed for the parcel record; its people fields (owner name, owner mailing address, entity principals, deed parties) are delivered to accounts only, so send your Authorization: Bearer pz_… header with the payment to receive them. Without it they arrive as null with a people_fields marker, and the price is computed on exactly what is delivered. 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:119:11906402/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:119:11906402/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.

# PROPRAVEN_API_KEY holds your pz_ key (it unlocks the people fields)
curl -i "https://api.propraven.com/api/v1/parcels/37:119:11906402/report" \
  -H "Authorization: Bearer $PROPRAVEN_API_KEY" \
  -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 and the same wallet: each lead carries the owner's name and mailing address, returned once the payment settles (no account needed). An unpaid call without an account gets HTTP 401 code: account_required.

Preview first: the preview is free, needs no account, 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: with your Authorization header, a 402 carrying that exact total, or — adding an X-PAYMENT header — the full unmasked set with the settlement receipt in X-PAYMENT-RESPONSE. A paid plan includes lead feeds. Over MCP it is one tool, find_leads.

# PROPRAVEN_API_KEY holds your pz_ key (lead delivery needs an account)
curl -i "https://api.propraven.com/api/v1/leads/find?signal=distressed&state=NC&county=183&limit=50" \
  -H "Authorization: Bearer $PROPRAVEN_API_KEY" \
  -H "X-PAYMENT: <base64 signed x402 PaymentPayload>"

Each delivered lead carries owner_contact: the owner's best mailing address, read from one address family of the record with its ZIP and flagged mail_ready. Add mail_ready=true to keep only parcels with a complete mailing address. In a large state add county too: a pull too broad to finish in time returns HTTP 503 code: lead_read_timeout, and nothing is charged.

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 → A funded wallet is enough to pay via x402 for parcel data. People data (owner names, owner mailing addresses, lead lists, owner cards) also needs the key, sent with the payment.

Resources

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