{"openapi":"3.1.0","info":{"title":"CAVE Title & Agent API","version":"2.1.0","description":"AI-agent-first real estate settlement API. 5 specialized AI agents for property discovery, negotiation, title verification, settlement execution, and lending. Supports dual payment modes: x402 (fast, transparent) and x402-PRIVATE (encrypted, confidential) for per-request micropayments in USDC. Built on Polygon blockchain with DeFi integration.","contact":{"name":"Automa Labs AI","email":"Allen@Automalabs.xyz","url":"https://cavetitle.xyz"},"license":{"name":"Proprietary","url":"https://cavetitle.xyz/terms"},"x-logo":{"url":"https://cavetitle.xyz/logo.png"},"x-payment-methods":{"x402":{"name":"x402 (Standard)","description":"Fast, transparent, public payments","visibility":"public","speed":"~2 seconds","platformFee":"0.5%","network":"Polygon","currency":"USDC"},"x402-PRIVATE":{"name":"x402-PRIVATE (Premium)","description":"Encrypted, private, confidential payments with FHE","visibility":"encrypted","speed":"~4-6 seconds","platformFee":"1.5%","network":"Polygon","currency":"USDC","encryption":"AES-256-GCM + FHE","features":["Zero-Knowledge Proofs","MEV Protection","Threshold Decryption"]}}},"servers":[{"url":"https://cavetitle.xyz/api/v2","description":"Production API"}],"paths":{"/agents/discovery":{"post":{"operationId":"discoveryAgentSearch","summary":"Search for properties using AI-powered Discovery Agent","description":"Scans MLS, public records, and social signals to find properties matching criteria. Identifies off-market opportunities. Returns property listings with valuations powered by PARCL/Polymarket. Choose payment method: x402 ($0.50) or x402-PRIVATE ($1.50).","tags":["Discovery Agent"],"parameters":[{"name":"paymentMethod","in":"query","schema":{"type":"string","enum":["x402","x402-PRIVATE"],"default":"x402"},"description":"Payment method: x402 (public) or x402-PRIVATE (encrypted)"},{"name":"privacyLevel","in":"query","schema":{"type":"string","enum":["public","private"],"default":"public"},"description":"Privacy level for transaction"}],"x-payment":{"methods":[{"type":"x402","currency":"USDC","amount":0.5,"network":"Polygon","visibility":"public","speed":"~2 seconds","gasCost":"$0.50-1.00","platformFee":"0.5%"},{"type":"x402-PRIVATE","currency":"USDC","amount":1.5,"network":"Polygon","visibility":"encrypted","encryption":"AES-256-GCM + FHE","speed":"~4-6 seconds","gasCost":"$2.00-3.50","platformFee":"1.5%","features":["Zero-Knowledge Proofs","MEV Protection","Threshold Decryption"]}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveryRequest"}}}},"responses":{"200":{"description":"Property search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveryResponse"}}}},"402":{"description":"Payment Required - x402 or x402-PRIVATE payment instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}}}}},"/agents/title":{"post":{"operationId":"titleAgentSearch","summary":"Perform automated title search and verification","description":"Automated title search with lien detection, ownership verification, and chain of title analysis. 99.95% accuracy. Results verified with zero-knowledge proofs. Choose payment method: x402 ($15.00) or x402-PRIVATE ($45.00).","tags":["Title Agent"],"parameters":[{"name":"paymentMethod","in":"query","schema":{"type":"string","enum":["x402","x402-PRIVATE"],"default":"x402"},"description":"Payment method: x402 (public) or x402-PRIVATE (encrypted)"}],"x-payment":{"methods":[{"type":"x402","currency":"USDC","amount":15,"network":"Polygon","visibility":"public","platformFee":"0.5%"},{"type":"x402-PRIVATE","currency":"USDC","amount":45,"network":"Polygon","visibility":"encrypted","encryption":"AES-256-GCM + FHE","platformFee":"1.5%"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleSearchRequest"}}}},"responses":{"200":{"description":"Title search results with verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleSearchResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}}}}},"/agents/settlement":{"post":{"operationId":"settlementAgentExecute","summary":"Execute real estate settlement in 15 seconds","description":"Smart contract settlement on Polygon blockchain. Atomic swap ensures simultaneous fund/title exchange. Zero wire fraud. Includes deed generation, fund disbursement, and blockchain recording. Choose payment method: x402 ($330.00) or x402-PRIVATE ($990.00).","tags":["Settlement Agent"],"parameters":[{"name":"paymentMethod","in":"query","schema":{"type":"string","enum":["x402","x402-PRIVATE"],"default":"x402"},"description":"Payment method: x402 (public) or x402-PRIVATE (encrypted)"}],"x-payment":{"methods":[{"type":"x402","currency":"USDC","amount":330,"network":"Polygon","visibility":"public","platformFee":"0.5%"},{"type":"x402-PRIVATE","currency":"USDC","amount":990,"network":"Polygon","visibility":"encrypted","encryption":"AES-256-GCM + FHE","platformFee":"1.5%"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementRequest"}}}},"responses":{"200":{"description":"Settlement executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}}}}},"/agents/lender":{"post":{"operationId":"lenderAgentOriginate","summary":"Automated loan origination with AI underwriting","description":"AI-powered loan origination with instant underwriting. Analyzes income, credit, and property value. Funds via DeFi Lend liquidity pools. 8-12% yields for capital providers. Choose payment method: x402 ($50.00) or x402-PRIVATE ($150.00).","tags":["Lender Agent"],"parameters":[{"name":"paymentMethod","in":"query","schema":{"type":"string","enum":["x402","x402-PRIVATE"],"default":"x402"},"description":"Payment method: x402 (public) or x402-PRIVATE (encrypted)"}],"x-payment":{"methods":[{"type":"x402","currency":"USDC","amount":50,"network":"Polygon","visibility":"public","platformFee":"0.5%"},{"type":"x402-PRIVATE","currency":"USDC","amount":150,"network":"Polygon","visibility":"encrypted","encryption":"AES-256-GCM + FHE","platformFee":"1.5%"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LenderRequest"}}}},"responses":{"200":{"description":"Loan originated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LenderResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}}}}},"/agents/negotiation":{"post":{"operationId":"negotiationAgentStart","summary":"Start autonomous price negotiation session","description":"AI-powered negotiation engine that optimizes for speed, price, and terms. Handles counteroffers and contingencies automatically. Choose payment method: x402 ($25.00) or x402-PRIVATE ($75.00).","tags":["Negotiation Agent"],"parameters":[{"name":"paymentMethod","in":"query","schema":{"type":"string","enum":["x402","x402-PRIVATE"],"default":"x402"},"description":"Payment method: x402 (public) or x402-PRIVATE (encrypted)"}],"x-payment":{"methods":[{"type":"x402","currency":"USDC","amount":25,"network":"Polygon","visibility":"public","platformFee":"0.5%"},{"type":"x402-PRIVATE","currency":"USDC","amount":75,"network":"Polygon","visibility":"encrypted","encryption":"AES-256-GCM + FHE","platformFee":"1.5%"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiationRequest"}}}},"responses":{"200":{"description":"Negotiation session result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiationResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}}}}},"/valuation":{"get":{"operationId":"getPropertyValuation","summary":"Get PARCL-powered property valuation","description":"Real-time property valuation powered by PARCL (Polymarket). Returns estimated value, confidence score, and comparable sales. Choose payment method: x402 ($1.00) or x402-PRIVATE ($3.00).","tags":["Valuation"],"parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Full property address"},{"name":"paymentMethod","in":"query","schema":{"type":"string","enum":["x402","x402-PRIVATE"],"default":"x402"},"description":"Payment method: x402 (public) or x402-PRIVATE (encrypted)"}],"x-payment":{"methods":[{"type":"x402","currency":"USDC","amount":1,"network":"Polygon","visibility":"public","platformFee":"0.5%"},{"type":"x402-PRIVATE","currency":"USDC","amount":3,"network":"Polygon","visibility":"encrypted","encryption":"AES-256-GCM + FHE","platformFee":"1.5%"}]},"responses":{"200":{"description":"Property valuation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequired"}}}}}}},"/health":{"get":{"operationId":"healthCheck","summary":"API health check for agent orchestrators","description":"Returns service health status, latency metrics, and agent availability. No payment required.","tags":["System"],"responses":{"200":{"description":"Service health status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"components":{"schemas":{"DiscoveryRequest":{"type":"object","required":["location"],"properties":{"query":{"type":"string","description":"Natural language search query"},"location":{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"}}},"priceRange":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"propertyType":{"type":"string","enum":["residential","commercial","mixed"]}}},"DiscoveryResponse":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"},"pricing":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["x402","x402-PRIVATE"]},"cost":{"type":"number"},"currency":{"type":"string"},"transactionId":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]}}}}},"TitleSearchRequest":{"type":"object","required":["propertyAddress"],"properties":{"propertyAddress":{"type":"string"},"county":{"type":"string"},"includeLinSearch":{"type":"boolean","default":true}}},"TitleSearchResponse":{"type":"object","properties":{"titleStatus":{"type":"string"},"liens":{"type":"array","items":{"type":"object"}},"ownership":{"type":"object"},"zkProofVerified":{"type":"boolean"},"pricing":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["x402","x402-PRIVATE"]},"cost":{"type":"number"},"currency":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]}}}}},"SettlementRequest":{"type":"object","required":["buyerAddress","sellerAddress","propertyAddress","salePrice"],"properties":{"buyerAddress":{"type":"string"},"sellerAddress":{"type":"string"},"propertyAddress":{"type":"string"},"salePrice":{"type":"number"},"closingDate":{"type":"string","format":"date"}}},"SettlementResponse":{"type":"object","properties":{"status":{"type":"string","enum":["completed","pending","failed"]},"transactionHash":{"type":"string"},"blockNumber":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"},"pricing":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["x402","x402-PRIVATE"]},"cost":{"type":"number"},"currency":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]}}}}},"LenderRequest":{"type":"object","required":["borrowerIncome","creditScore","propertyValue"],"properties":{"borrowerIncome":{"type":"number"},"creditScore":{"type":"integer"},"propertyValue":{"type":"number"},"loanAmount":{"type":"number"}}},"LenderResponse":{"type":"object","properties":{"loanApproved":{"type":"boolean"},"interestRate":{"type":"number"},"loanAmount":{"type":"number"},"fundingSource":{"type":"string"},"pricing":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["x402","x402-PRIVATE"]},"cost":{"type":"number"},"currency":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]}}}}},"NegotiationRequest":{"type":"object","required":["propertyAddress","initialOffer"],"properties":{"propertyAddress":{"type":"string"},"initialOffer":{"type":"number"},"preferences":{"type":"object"}}},"NegotiationResponse":{"type":"object","properties":{"negotiationStatus":{"type":"string"},"finalOffer":{"type":"number"},"terms":{"type":"object"},"pricing":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["x402","x402-PRIVATE"]},"cost":{"type":"number"},"currency":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]}}}}},"ValuationResponse":{"type":"object","properties":{"estimatedValue":{"type":"number"},"confidenceScore":{"type":"number"},"comparableSales":{"type":"array","items":{"type":"object"}},"pricing":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["x402","x402-PRIVATE"]},"cost":{"type":"number"},"currency":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]}}}}},"X402PaymentRequired":{"type":"object","properties":{"paymentMethods":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["x402","x402-PRIVATE"]},"amount":{"type":"number"},"currency":{"type":"string"},"network":{"type":"string"},"visibility":{"type":"string","enum":["public","encrypted"]},"platformFee":{"type":"string"}}}},"requestId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"timestamp":{"type":"string","format":"date-time"},"latency":{"type":"object","properties":{"p50":{"type":"number"},"p99":{"type":"number"}}},"agents":{"type":"object","properties":{"discovery":{"type":"boolean"},"title":{"type":"boolean"},"settlement":{"type":"boolean"},"lender":{"type":"boolean"},"negotiation":{"type":"boolean"}}}}}}}}