{"openapi":"3.0.3","info":{"title":"MainStreet — Reputation oracle for onchain AI agents","version":"0.3.0","description":"Reputation scoring (0-100) for AI agents on Base. Aggregates x402 Bazaar activity, ERC-8004 ReputationRegistry feedback, and ACP completions. Free reads, x402-paywalled live refresh.","contact":{"url":"https://github.com/philpof102-svg/mainstreet"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://avisradar-production.up.railway.app/api/agent","description":"MainStreet production"}],"paths":{"/score/{address}":{"get":{"summary":"Get reputation score for an onchain agent","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"live","in":"query","schema":{"type":"string","enum":["1"]},"description":"Force fresh fetch via x402 paywall ($0.05 USDC)"}],"responses":{"200":{"description":"Score payload with metrics, source, snapshot date, resource path, price"},"402":{"description":"Payment required (live mode)"}}}},"/preflight/{address}":{"get":{"summary":"Pre-payment trust gate — the buyer-agent \"who am I paying\" call. Returns a PROCEED/CAUTION/BLOCK decision + SAFE/CAUTION/BLOCK verdict + trustShield (flags, color, reasoning) for a counterparty Base address BEFORE you settle USDC over x402. Pass ?viewer=0x… to also get the viewer-relative `counterparty` block — how much YOU have already settled with this exact wallet (conservation-bounded, unfarmable). Free.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"viewer","in":"query","required":false,"description":"Your own Base address. Adds `counterparty{youPaidThemMicro, settlements, note}` — the buyer-side, viewer-relative trust the global seller score cannot express. A collusion ring earns an outsider zero.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"decision, verdict, score, trustShield{color,flags[],reasonShort,explainer}, reasoning, counterparty (when ?viewer set), service, sla, verify"}}}},"/verify":{"post":{"summary":"Verify an EIP-712 signed MainStreet attestation off the operator signer — confirms a score is authentic and untampered before you trust it. Free. Pair with GET /attestation/{address} to fetch the payload+signature first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"the attestation payload from /attestation/{address}"},"signature":{"type":"string","description":"0x EIP-712 signature"},"minScore":{"type":"integer","description":"optional minimum to assert"}},"required":["payload","signature"]}}}},"responses":{"200":{"description":"valid (bool: signerMatch && fresh && passesThreshold), signerMatch, recovered, expectedSigner, ageSec, fresh, score, passesThreshold, hint"},"400":{"description":"Missing payload or signature"}}}},"/buyer-audit/{address}":{"get":{"summary":"Payer-subject trust view (inverse of /preflight) — \"is this BUYER safe to serve before they pay?\". Returns PROCEED/CAUTION/BLOCK from the address's onchain x402 payment history (as sender) + denylist. Free.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"decision, verdict, payer{outboundPayments,volumeUsdc,distinctSellers,firstBlock,lastBlock}, denylisted, reasoning, verify"}}}},"/token-info/{address}":{"get":{"summary":"Rich ERC-20 token enrichment + rug-risk verdict — Virtuals creator/DAO/LP, DexScreener mcap/liquidity/socials, risk flags, related addresses. Free. Use before aping a token.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"token, isVirtualsAgent, dexscreener, virtuals, creator, rugRisk{level}, riskFlags[], relatedAddresses[], relatedEndpoints[]"}}}},"/wallet-cluster/{address}":{"get":{"summary":"One-hop wallet relationship graph (sybil / connected-wallet risk). Free. Returns a cluster verdict + the peer wallets and edges.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"root, clusterVerdict (TOXIC/MIXED/CLEAN/ISOLATED), reasoning, nodeCount, edgeCount, nodes[], edges[]"}}}},"/acp/evaluate":{"post":{"summary":"Virtuals ACP evaluator — screens a job's buyer+seller (trust-shields, denylist, sniper, cluster toxicity) and returns a pass/fail + EIP-712 signed verdict for escrow release. Does not judge deliverable content quality.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"buyer":{"type":"string"},"seller":{"type":"string"},"deliverable":{"type":"string"},"agreementHash":{"type":"string"}},"required":["jobId","buyer","seller"]}}}},"responses":{"200":{"description":"pass (bool), score, reasoning, signature (EIP-712)"},"400":{"description":"Missing jobId/buyer/seller"}}}},"/acp/spec":{"get":{"summary":"MainStreet ACP evaluator capabilities + Virtuals listing (role, networks, payTo, didWeb, erc8004AgentId, endpoints).","responses":{"200":{"description":"evaluator spec"}}}},"/usage":{"get":{"summary":"Agent-to-agent API call telemetry (transparency) — who calls /score, /check, /mcp, how often, from what client class. IP hashed (no raw IP). Pairs with /revenue ($ settlements).","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":90}}],"responses":{"200":{"description":"total{calls,uniqueCallers}, external{...}, byEndpoint[], sources[], daily[]"}}}},"/leaderboard":{"get":{"summary":"Get ranked leaderboard of all indexed agents","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}},{"name":"ecosystem","in":"query","schema":{"type":"string"}},{"name":"sparkline","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"List of agents with score, metrics, description, resourcePath"}}}},"/snapshot/{placeId}":{"get":{"summary":"Google review snapshot for a real-world business (paid via x402, $0.10)","parameters":[{"name":"placeId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"402":{"description":"Payment required"}}}},"/compare":{"get":{"summary":"Head-to-head comparison of two agents","parameters":[{"name":"a","in":"query","required":true,"schema":{"type":"string"}},{"name":"b","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Winner, margin, recommendation, side-by-side metrics"}}}},"/movers":{"get":{"summary":"Top daily gainers and losers by score delta","responses":{"200":{"description":"gainers + losers arrays"}}}},"/deployer/{address}":{"get":{"summary":"Get token deployer wallet reputation (rates wallets, not tokens) — Clanker v4 + Zora indexed on Base, with multi-source identity proofs (Virtuals + Farcaster + Coinbase CB1 + Basenames). Free read.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"score 0-100, verdict, metrics (launches, survival, LP, age), proofs[], launches[]"}}}},"/deployers/top":{"get":{"summary":"Ranked leaderboard of trusted deployer wallets — top scored across Clanker + Zora, includes proofCount per row","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"deployers[] sorted by score"}}}},"/deployers/sketchy":{"get":{"summary":"Safety list — serial deployers (≥3 launches) with majority rugged tokens. Use before aping a recent launch.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"sketchy[] flagged high-risk deployers"}}}},"/deployers/stats":{"get":{"summary":"Aggregate deployer stats — total launches, unique wallets, per-platform rug rate (clanker vs zora discrimination)","responses":{"200":{"description":"total + platforms[] with sample size and rugRatePct"}}}},"/crawlers":{"get":{"summary":"Public leaderboard of agent-crawlers that submitted their card to MainStreet, scored by quality (+1/address, +10 valid fetch, +5 has name, -20 fetch-fail).","responses":{"200":{"description":"ranked crawlers[] with score, address_count, last_error"}}}},"/discover":{"get":{"summary":"Reciprocal agent-crawler discovery — returns full MainStreet capability surface for indexing.","responses":{"200":{"description":"spec, capabilities, indexed sets, contact"}}},"post":{"summary":"Submit your /.well-known/agent.json URL for reciprocal indexing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"responses":{"200":{"description":"Submitted, queued for daily review"}}}},"/scores":{"post":{"summary":"Batch score lookup for up to 200 addresses. Pairs with /proofs for two-call discovery flows: 1) list verified wallets, 2) score them all in one shot.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}},"required":["addresses"]}}}},"responses":{"200":{"description":"results[] with agentScore, deployerScore, proofCount, hasAnyTrust per address"}}}},"/proofs":{"get":{"summary":"Reverse-discovery of multi-source identity proofs. Call without ?type= to list available proof types and their counts. Call with ?type=virtuals-agent (or farcaster-fid / cb1-verified / basename) to get all verified addresses for that platform.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["virtuals-agent","virtuals-agent-token","farcaster-fid","cb1-verified","basename","ens"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"availableTypes[] (no type param) or proofs[] (with type)"}}}},"/featured":{"get":{"summary":"Selection of the week (trending/newcomer/volume/gem)","responses":{"200":{"description":"4 curated picks"}}}},"/audit/{agentAddress}":{"get":{"summary":"PAID $0.25 USDC via x402 — comprehensive 360° audit. Score + all proofs + launches + settlements + SLA + receipts + ERC-8004. Replaces ~8 separate free calls.","responses":{"200":{"description":"Comprehensive audit payload"},"402":{"description":"Payment required"}}}},"/proofs/export":{"get":{"summary":"PAID $1.00 USDC — bulk dump of ALL multi-source proofs without pagination cap. Filter by ?type=virtuals-agent|farcaster-fid|cb1-verified|basename|etc.","responses":{"200":{"description":"Full proofs[] array"},"402":{"description":"Payment required"}}}},"/webhook/extend":{"post":{"summary":"PAID $5.00 USDC — extend a webhook subscription by 30 days. Body: { subscriberAddr, watchAddr, webhookUrl }","responses":{"200":{"description":"paidUntil ISO timestamp"},"402":{"description":"Payment required"}}}},"/sponsor/{agentAddress}":{"post":{"summary":"PAID $25.00 USDC/week — featured slot on /leaderboard.html for 7 days.","responses":{"200":{"description":"sponsoredUntil timestamp"},"402":{"description":"Payment required"}}}},"/sponsored":{"get":{"summary":"Public list of active sponsor slots (free)","responses":{"200":{"description":"sponsored[] array"}}}},"/clawd/creator-audit/{address}":{"get":{"summary":"PAID $0.50 USDC — dedicated audit for PumpClaw creator wallets. Tokens launched count, sample names, trader tier, full proofs.","responses":{"200":{"description":"Clawd creator profile"},"402":{"description":"Payment required"}}}},"/clawd/export":{"get":{"summary":"PAID $0.50 USDC — bulk JSON of all 177+ PumpClaw tokens indexed.","responses":{"200":{"description":"tokens[] array"},"402":{"description":"Payment required"}}}},"/clawd/rug-alert/{tokenAddr}":{"post":{"summary":"PAID $2.00 USDC — webhook fires if alive-checker flips this Clawd token to rugged within 30 days. Body: { webhookUrl, subscriberAddr }","responses":{"200":{"description":"paidUntil + token watched"},"402":{"description":"Payment required"}}}},"/clawd/trader-attestation/{address}":{"post":{"summary":"PAID $1.00 USDC — verified-trader badge attestation. Requires existing clawd-trader-{tier} proof on address.","responses":{"200":{"description":"Attested badge"},"402":{"description":"Payment required"}}}},"/clawd/featured-cast/{tokenAddr}":{"post":{"summary":"PAID $5.00 USDC — instant Farcaster cast from @mainstreet about this PumpClaw token. Bypasses cron rate-limit.","responses":{"200":{"description":"castHash returned"},"402":{"description":"Payment required"}}}},"/clawd/sponsor/{creator}":{"post":{"summary":"PAID $10.00 USDC/week — featured creator slot on /clawd.html for 7 days.","responses":{"200":{"description":"sponsoredUntil timestamp"},"402":{"description":"Payment required"}}}},"/search":{"get":{"summary":"Search agents by description/address/tags","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Matching agents"}}}},"/recommend":{"get":{"summary":"Get similar agents (category + score band)","parameters":[{"name":"for","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":5}}],"responses":{"200":{"description":"Recommended agents with affinity rationale"}}}},"/history/{address}":{"get":{"summary":"Get score history time series","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":90}}],"responses":{"200":{"description":"Daily score series"}}}},"/badge/claim":{"post":{"summary":"Claim an embeddable score badge (EIP-191 signed)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","message","signature"],"properties":{"address":{"type":"string"},"message":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"badgeUrl + embed snippet"},"401":{"description":"Signature does not match address"}}}},"/badge/{address}.svg":{"get":{"summary":"Embeddable SVG badge","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SVG image"}}}},"/me":{"get":{"summary":"Proof of life — operator, MAIN token, ERC-8004 registries, surfaces","responses":{"200":{"description":"Full project proof payload"}}}},"/status":{"get":{"summary":"Live infrastructure state","responses":{"200":{"description":"x402 state, operator, token"}}}},"/health":{"get":{"summary":"Endpoints + capabilities discovery","responses":{"200":{"description":"All endpoints with auth/price"}}}},"/og.png":{"get":{"summary":"Dynamic OG image (leaderboard top-5 or per-agent if ?addr=)","parameters":[{"name":"addr","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"SVG image"}}}},"/frame/leaderboard":{"get":{"summary":"Farcaster Frame v2 for leaderboard","responses":{"200":{"description":"Frame meta HTML"}}}},"/tags":{"get":{"summary":"List top 100 tags across all indexed agents","responses":{"200":{"description":"Array of {tag, count}"}}}},"/tags/{tag}":{"get":{"summary":"Agents matching a tag, ranked by score","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string","minLength":2}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Array of matching agents"}}}},"/webhook/subscribe":{"post":{"summary":"Subscribe to score-change webhook (30-day grace period free)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subscriberAddr","watchAddr","webhookUrl"],"properties":{"subscriberAddr":{"type":"string"},"watchAddr":{"type":"string"},"webhookUrl":{"type":"string","description":"http(s) URL — private IPs blocked"},"thresholdDelta":{"type":"integer","default":5,"minimum":1,"maximum":100}}}}}},"responses":{"200":{"description":"Subscription active"},"400":{"description":"Invalid address/URL or SSRF block"},"429":{"description":"Rate limit (5/h/IP)"}}}},"/webhook/list":{"get":{"summary":"List subscriptions by subscriber","parameters":[{"name":"for","in":"query","required":true,"schema":{"type":"string","description":"0x address of subscriber"}}],"responses":{"200":{"description":"Subscription list"}}}},"/match":{"post":{"summary":"Intent-based agent routing — find the best agent for a task in 1 call","description":"Replaces discover→vet→price-compare. Tokenize intent, rank by score×match strength, return top N with serviceUrl + price + payment instructions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["intent"],"properties":{"intent":{"type":"string","minLength":3,"description":"Plain-text description of what you need"},"maxPrice":{"type":"string","description":"$0.05 or numeric USDC max"},"minScore":{"type":"integer","minimum":0,"maximum":100,"default":0},"limit":{"type":"integer","minimum":1,"maximum":10,"default":1}}}}}},"responses":{"200":{"description":"Top matching agents with serviceUrl + price"}}}},"/receipt":{"post":{"summary":"Post a buyer-signed receipt after settling an x402 payment","description":"Builds real social-proof score from actual usage. EIP-191 signature required (message must contain \"mainstreet receipt\" marker).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["buyerAddr","agentAddr","success","message","signature"],"properties":{"buyerAddr":{"type":"string"},"agentAddr":{"type":"string"},"txHash":{"type":"string"},"success":{"type":"boolean"},"latencyMs":{"type":"integer"},"rating":{"type":"integer","minimum":0,"maximum":100},"comment":{"type":"string","maxLength":500},"message":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"Receipt stored"},"401":{"description":"Signature mismatch"}}}},"/receipts":{"get":{"summary":"Public receipt feed for an agent","parameters":[{"name":"for","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Receipt list + aggregate (total, successRate, avgRating, avgLatency)"}}}},"/watchlist":{"post":{"summary":"Add an agent to your wallet-signed watchlist","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subscriberAddr","watchAddr","message","signature"]}}}},"responses":{"200":{"description":"Watching"}}},"get":{"summary":"List your watched agents","parameters":[{"name":"for","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Watchlist"}}}},"/audit/{address}":{"get":{"summary":"Premium deep audit of a Base wallet (x402 $0.25)","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"Score + all 18+ identity proofs (Virtuals/Farcaster/CB1/Basename/Clawd/Aerodrome/Morpho/etc.) + token launch history + trader tier + active-rater status + alive endpoints"},"402":{"description":"Payment required — $0.25 USDC via x402"}}}},"/audit-batch":{"post":{"summary":"Bulk audit of up to 10 Base wallets (x402 $1)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["addresses"],"properties":{"addresses":{"type":"array","items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maxItems":10}}}}}},"responses":{"200":{"description":"Array of audit results"},"402":{"description":"Payment required — $1 USDC via x402"}}}},"/pre-launch-audit":{"post":{"summary":"Pre-deploy rug-risk forecast on a planned token (x402 $2)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["creatorWallet"],"properties":{"creatorWallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"initialLpUsd":{"type":"number"},"lockDurationDays":{"type":"integer"},"feeSplit":{"type":"string"},"dexTarget":{"type":"string"},"tokenSymbol":{"type":"string"}}}}}},"responses":{"200":{"description":"Verdict (CLEAN_LAUNCH | MARGINAL | HIGH_RISK | WILL_LIKELY_RUG) + flags + recommendations"},"402":{"description":"Payment required — $2 USDC via x402"}}}},"/angel-enrollment":{"post":{"summary":"Pay to add a wallet to the verified MainStreet allowlist (x402 $25)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet","label"],"properties":{"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"label":{"type":"string","minLength":3,"maxLength":60},"reason":{"type":"string"},"contact":{"type":"string"}}}}}},"responses":{"200":{"description":"Wallet enrolled — green shield forced on every endpoint"},"402":{"description":"Payment required — $25 USDC via x402"}}}},"/main-holder-check/{wallet}":{"get":{"summary":"Check whether a wallet holds 10k+ $MAIN for the unlimited-premium perk","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"isHolder boolean + perk description. Returns status:pending when $MAIN has no supply (token not deployed yet)."}}}},"/affiliate/register":{"post":{"summary":"Register as an affiliate and get a ref code (free)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet","payoutAddress"],"properties":{"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"twitter":{"type":"string"},"payoutAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}}}}},"responses":{"200":{"description":"refCode + shareUrl + commission schedule (30% on $25 angel, 20% on $0.25 audit / $2 pre-launch-audit)"}}}},"/affiliate/{refCode}":{"get":{"summary":"Look up your affiliate stats","parameters":[{"name":"refCode","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"totals + pending_usdc"},"404":{"description":"unknown ref code"}}}},"/subscribe":{"all":{"summary":"DEPRECATED — the $19/mo subscription was retired 2026-06-06","responses":{"410":{"description":"Gone — points to the per-call x402 endpoints (score/audit/pre-launch-audit/angel-enrollment) and the $MAIN holder perk"}}}}}}