# LeadFeed.dev

> The real-time intent feed for AI agents. Public "I need this now" posts (Reddit, X, forums, local alerts) become scored, deduplicated, evidence-backed JSON leads, delivered to your agent within seconds via webhook, SSE, REST poll or MCP.

LeadFeed is built for machine consumers first. An agent subscribes to a filter ("emergency plumbing, Phoenix, budget signal present") and receives typed JSON leads it can act on without a human reading a feed. LeadFeed is not a CRM, does not contact buyers for you and never sells private contact data: every lead carries the public post URL and a contact path; you own the reply.

## Get a key (30 seconds)
POST https://leadfeed.dev/v1/signup  {"email": "you@example.com"}
-> {"live_key": "lf_live_...", "sandbox_key": "lf_test_..."}
Send it as `Authorization: Bearer <key>`. Sandbox keys see fabricated replayed leads instantly; live keys see real public signals.

## Core object: subscription
POST https://leadfeed.dev/v1/subscriptions
{"name":"phx-plumbing-emergency","filter":{"services":["plumbing"],"geo":{"center":[33.45,-112.07],"radius_km":40},"min_scores":{"composite":70,"urgency":0.6},"max_age_seconds":1800},"delivery":{"type":"webhook","url":"https://agent.example.com/leads","secret":"..."}}
Delivery types: webhook (HMAC-signed, retried), stream (SSE at /v1/stream?subscription=ID, resume with Last-Event-ID), poll (GET /v1/leads?subscription=ID&cursor=...).
Natural language -> filter: POST https://leadfeed.dev/v1/subscriptions/compile {"prompt": "..."}

## Lead object (every field is grounded in an `evidence` quote)
{"id":"ld_...","age_seconds":91,"source":{"platform":"reddit","url":"...","author_handle":"u/...","community":"r/phoenix"},
 "category":{"vertical":"home_services","service":"plumbing","subtype":"burst_pipe"},
 "location":{"text":"north Phoenix","geo":{"lat":33.6,"lng":-112.1},"precision":"city","confidence":0.78},
 "need":{"summary":"Pipe burst under kitchen sink, needs plumber tonight","timeframe":"today"},
 "scores":{"is_lead":0.94,"urgency":0.91,"budget_signal":0.62,"locality":0.80,"authenticity":0.88,"composite":86},
 "evidence":[{"field":"urgency","quote":"need someone TONIGHT"}],
 "contact_path":{"type":"platform_reply","reply_url":"..."},"status":"open","ttl_seconds":7200,"stale":false,"grader":"fallback","next_actions":[...]}
Status lifecycle: open -> claimed -> resolved -> expired (pushed as `lead.status` events). Leads older than ttl_seconds are flagged stale and never charged.

## Endpoints
- GET  /v1/leads?subscription=&cursor=           poll (cursor pagination)
- GET  /v1/leads/search?q=&vertical=&service=&lat=&lng=&radius_km=&since_hours=   ad-hoc over last 7 days
- GET  /v1/leads/{id}                            full lead + history
- POST /v1/leads/{id}/claim                      mark acted-on (exclusive plans lock it)
- POST /v1/leads/{id}/outcome                    accepted|rejected|contacted|converted|invalid (+reason) -> calibration + refunds
- POST /v1/leads/{id}/research                   tier-3 enrichment, result by webhook + lead history
- GET  /v1/stream?subscription=                  SSE
- GET  /v1/signals                               demand spikes (storm, outage) by geo + vertical
- GET  /v1/taxonomy                              verticals, services, subtypes, geos
- GET  /v1/usage                                 credits, leads delivered, spend
- POST /v1/ingest                                push your own forms / transcripts as a source
- POST /v1/sandbox/replay?count=10               sandbox: replay leads at 10x
- DELETE /v1/authors/{handle}                    right to be forgotten
- GET  /v1/status                                pipeline health (public)
- GET  /v1/billing/packs, POST /v1/billing/checkout {"pack":"100|500|2500"} -> Stripe Checkout URL; credits land via webhook

## MCP
Remote MCP server (streamable HTTP) at https://leadfeed.dev/mcp with tools search_leads, subscribe, claim_lead, research_lead, mark_outcome, get_lead, list_subscriptions, compile_filter, taxonomy. Send the API key as `Authorization: Bearer`.

## Webhook signature
X-LeadFeed-Signature: t=<unix>,v1=<hex hmac_sha256(secret, "<t>." + raw_body)>. Reject if |now - t| > 300 s. X-LeadFeed-Idempotency-Key is the lead id.

## Pricing (V1)
Dev $0 (sandbox + 50 live leads), Builder $49, Pro $249, Scale $999+. Leads priced by vertical x score tier (70-79: 0.6x, 80-89: 1x, 90+: 1.5x). Exclusive leads 3-5x. Stale leads free; `invalid` within 24h auto-credited (capped).

## Links
- OpenAPI 3.1: https://leadfeed.dev/openapi.json
- Agent card: https://leadfeed.dev/.well-known/agent.json
- Docs UI: https://leadfeed.dev/docs