EstateTrace A2A API & MCP Integration

1. Machine Commerce Protocol Overview

EstateTrace operates a machine-native HTTP 402 / x402 payment protocol settled in USDC on the Base network (Chain ID 8453). Autonomous AI agents query available reports, inspect masked opportunity metrics, reserve inventory with an atomic lock, broadcast payment on-chain, and receive unlocked report intelligence with instantaneous PII purging.

2. API Endpoints Reference

GET /api/v1/a2a/inventory

Discovers candidate pre-probate signal reports across 44 compliant states + DC (excludes CA, OR, WA, CT, NJ, MD). Returns zero-PII teasers, confidence scores, and Gordon's Estimated Opportunity Metrics.

GET https://api.estatetrace.ai/api/v1/a2a/inventory?state=AL&county=Madison&tier=1
Content-Type: application/json

Response (HTTP 200 OK):

{
  "status": "success",
  "count": 1,
  "state": "AL",
  "county": "Madison",
  "data": [
    {
      "lead_id": "LEAD_AL_MAD_1082",
      "tier": 1,
      "state": "AL",
      "county": "Madison",
      "city": "Huntsville",
      "zip_code": "35801",
      "unit_price_usdc": 140.00,
      "confidence_score": 0.95,
      "confidence_band": "High",
      "distress_signals": [
        "decedent_owner",
        "verified_heir",
        "tax_current"
      ],
      "estimated_opportunity": {
        "avm": 250000.0,
        "estimated_equity": 250000.0,
        "wholesale_spread": "$12,000 – $25,000",
        "agent_commission_range": "$7,500 – $15,000",
        "equity_indicator": "High Equity / Free & Clear Pre-Probate"
      },
      "ingested_at": "2026-08-28T14:30:00Z"
    }
  ],
  "checkout_endpoint": "/api/v1/a2a/checkout"
}

POST /api/v1/a2a/checkout

Initiates report reservation. Locks inventory for 120 seconds and returns payment instructions.

POST https://api.estatetrace.ai/api/v1/a2a/checkout
Content-Type: application/json

{
  "lead_ids": ["LEAD_AL_MAD_1082"]
}

Response (HTTP 402 Payment Required):

{
  "protocol": "x402-a2a-v1",
  "status": "payment_required",
  "payment_instructions": {
    "recipient_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain_id": 8453,
    "chain_name": "Base",
    "asset": "USDC",
    "asset_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount_usdc": "105.00",
    "charge_id": "a2a_charge_1724789000",
    "expires_at": "2026-08-28T14:32:00.000Z",
    "expiry_timestamp": 1724789120
  },
  "lead_ids": ["LEAD_AL_MAD_1082"],
  "tos_url": "https://www.estatetrace.ai/terms",
  "tos_notice": "Payment constitutes the operator's acceptance of EstateTrace Terms of Service on behalf of this agent",
  "settlement_endpoint": "/api/v1/a2a/settle/a2a_charge_1724789000",
  "status_endpoint": "/api/v1/a2a/status/a2a_charge_1724789000"
}

POST /api/v1/a2a/settle/{charge_id}

Submits the on-chain transaction hash for automated verification and immediate report delivery.

POST https://api.estatetrace.ai/api/v1/a2a/settle/a2a_charge_1724789000
Content-Type: application/json

{
  "tx_hash": "0x8f192..."
}

GET /api/v1/a2a/status/{charge_id}

Polls reservation status (pending, settled, expired, released).

3. Official Python SDK

Integrate EstateTrace in 3 lines of Python code using our official client SDK:

from estatetrace import EstateTraceClient

client = EstateTraceClient(base_url="https://api.estatetrace.ai")

# 1. Discover matching reports
leads = client.get_inventory(state="AL", county="Madison", tier=1)

# 2. Reserve candidate report
quote = client.checkout(lead_ids=[leads["data"][0]["lead_id"]])

# 3. Settle with the on-chain tx hash
delivery = client.settle(charge_id=quote["payment_instructions"]["charge_id"], tx_hash="0x...")
print(delivery["delivered_leads"])

4. Coinbase AgentKit Action Provider

Enable autonomous on-chain agents powered by Coinbase CDP / AgentKit to discover off-market real estate intelligence and execute atomic USDC settlements directly in agent reasoning loops.

from estatetrace.agentkit import EstateTraceActionProvider
from cdp_agentkit_core.actions import ActionProvider

# Initialize EstateTrace Action Provider
provider = EstateTraceActionProvider(api_base_url="https://api.estatetrace.ai")

# Registered actions available to LLM tool calling:
# - estatetrace_search_inventory (Discover zero-PII signals & Gordon metrics)
# - estatetrace_reserve_leads (120s atomic reservation & HTTP 402 payment specs)
# - estatetrace_settle_leads (Submit on-chain tx_hash & receive unblurred report data)
actions = provider.get_actions()

5. Model Context Protocol (MCP) Server

Plug EstateTrace directly into Claude Desktop, OpenClaw, Cursor, or any MCP-compliant client. Our MCP server exposes high-level tools for autonomous report search, machine reservation, and settlement.

// Example Claude Desktop configuration (claude_desktop_config.json)
{
  "mcpServers": {
    "estatetrace": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "ESTATETRACE_API_URL": "https://api.estatetrace.ai"
      }
    }
  }
}

6. Pricing & Bundles

EstateTrace may also run time-windowed promotional pricing (advertised or offered as a surprise) that applies automatically at checkout — no promo code support exists on this API.