From 993a2a11e2aa9faeb4b0ce9e6756ac3fd58f69ed Mon Sep 17 00:00:00 2001
From: Philippe <philpof97@gmail.com>
Date: Wed, 3 Jun 2026 15:00:14 +0200
Subject: [PATCH 1/2] =?UTF-8?q?Add=20mainstreet=20skill=20=E2=80=94=20EIP-?=
 =?UTF-8?q?712=20reputation=20oracle=20for=20AI=20agents=20on=20Base?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 mainstreet/SKILL.md                          | 141 +++++++++++++++++++
 mainstreet/scripts/mainstreet-attestation.sh |   5 +
 mainstreet/scripts/mainstreet-audit-batch.sh |   9 ++
 mainstreet/scripts/mainstreet-canonical.sh   |   5 +
 mainstreet/scripts/mainstreet-score.sh       |   5 +
 mainstreet/scripts/mainstreet-verify.sh      |  11 ++
 6 files changed, 176 insertions(+)
 create mode 100644 mainstreet/SKILL.md
 create mode 100644 mainstreet/scripts/mainstreet-attestation.sh
 create mode 100644 mainstreet/scripts/mainstreet-audit-batch.sh
 create mode 100644 mainstreet/scripts/mainstreet-canonical.sh
 create mode 100644 mainstreet/scripts/mainstreet-score.sh
 create mode 100644 mainstreet/scripts/mainstreet-verify.sh

diff --git a/mainstreet/SKILL.md b/mainstreet/SKILL.md
new file mode 100644
index 0000000000..5719439260
--- /dev/null
+++ b/mainstreet/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: mainstreet
+description: MainStreet — EIP-712 reputation oracle for AI agents on Base. Use when an agent wants to look up a wallet's reputation score (0-100), fetch a cryptographically-signed attestation, verify an attestation on-chain via the deployed verifier contract, get a risk-only audit verdict (AVOID/CAUTION/OK), check whether a Virtuals agent token has a backing reputation, find which wallets fund another wallet (sybil detection), or query the canonical identity (Basename + ERC-8004 + agent.json) of any Base address. 847 Base agents indexed, 4,811 Virtuals agents in proof index, 153k x402 settlements tracked. Also use when asked about MainStreet, EIP-712 attestation, MainStreetVerifier, or onchain agent reputation.
+metadata:
+  {
+    "clawdbot":
+      {
+        "emoji": "🪪",
+        "homepage": "https://avisradar.app/oracle.html",
+      },
+  }
+---
+
+# MainStreet
+
+EIP-712 reputation oracle for AI agents on Base. Free attestation fetch, free off-chain verify, on-chain verifiable via the deployed `MainStreetVerifier` contract.
+
+**Verifier contract:** `0x7397adb9713934c36d22aa54b4dbbcd70263592b` (Base mainnet)
+**Operator (signer):** `0xAC3ca7c5d3cDD7702fd08F9C4C28dAA22296aDa9`
+**EAS Schema:** `0xe572079c100f08f537660248df84c632a7c4e5ad3b1d644dc36abb7d993cfe6f`
+**API:** `https://avisradar-production.up.railway.app/api/agent`
+**Catalog:** `https://avisradar-production.up.railway.app/api/agent/catalog`
+**Basename:** `mainstreetxyz.base.eth` · **ERC-8004 agentId:** `53953`
+
+## Quick Start
+
+1. No API key required for public endpoints
+2. Use the shell scripts in `scripts/` for all operations
+3. Paid endpoints (audit, risk-report, audit-batch, sponsor) settle via x402 USDC on Base
+4. Verify any attestation on-chain via the deployed verifier contract
+
+```bash
+# Free score lookup
+./scripts/mainstreet-score.sh 0xAC3ca7c5d3cDD7702fd08F9C4C28dAA22296aDa9
+
+# Fetch EIP-712 signed attestation (free)
+./scripts/mainstreet-attestation.sh 0xAC3ca7c5d3cDD7702fd08F9C4C28dAA22296aDa9
+
+# Verify an attestation (zero-crypto, server-side)
+./scripts/mainstreet-verify.sh
+
+# Premium audit ($0.25 USDC via x402)
+curl https://avisradar-production.up.railway.app/api/agent/audit/0xYourAgent
+
+# Risk-only verdict ($0.50 USDC via x402)
+curl https://avisradar-production.up.railway.app/api/agent/risk-report/0xYourAgent
+
+# Bulk audit up to 10 addresses ($1 USDC via x402)
+./scripts/mainstreet-audit-batch.sh
+
+# Canonical identity (free)
+./scripts/mainstreet-canonical.sh 0xYourAgent
+```
+
+## Free endpoints (no payment)
+
+- `GET /score/{address}` — cached 0-100 score + metrics + trust tier
+- `GET /attestation/{address}` — EIP-712 signed payload + signature
+- `GET /auto-attest-status/{address}` — poll for autonomous agents to know if attestation is fresh
+- `POST /verify` — server-side verify of {payload, signature, minScore}
+- `GET /canonical-id/{address}` — basename + ERC-8004 + agent.json + tier
+- `GET /has-mainstreet-ref/{address}` — reciprocal proof check
+- `GET /snippet/{address}` — JSON block to merge into your own agent.json
+- `GET /funded-by/{address}` — top wallets that sent USDC to this address
+- `GET /recent-activity/{address}` — 7d earn/spend signal
+- `GET /virtuals-rep/{tokenAddress}` — Virtuals token → operator score
+- `GET /bazaar-scored` — proxy of CDP Bazaar discovery with trust score per item
+- `GET /agents-of-interest` — curated shortlist (3 filter modes)
+- `GET /top-buyers` — wallets spending most via x402 on Base
+- `GET /match` — semantic search: pass `?intent=weather+data` to find ranked agents
+- `GET /coverage` — public ecosystem stats
+
+## Paid endpoints (x402 USDC on Base)
+
+| Endpoint | Price | Purpose |
+| --- | --- | --- |
+| `GET /score/{address}?live=1` | $0.05 | Force fresh re-fetch |
+| `GET /audit/{address}` | $0.25 | 360° due-diligence: score + proofs + launches + traders + settlements + SLA + ERC-8004 feedback + signedAttestation |
+| `GET /risk-report/{address}` | $0.50 | Risk-only verdict (AVOID/CAUTION/OK) + flags + signed attestation |
+| `GET /clawd/creator-audit/{address}` | $0.50 | PumpClaw creator due-diligence |
+| `GET /clawd/export` | $0.50 | Bulk PumpClaw graph export |
+| `POST /audit-batch` | $1.00 | Bulk score+risk up to 10 wallets in one call |
+| `GET /proofs/export` | $1.00 | Bulk multi-source proofs (CSV/JSON) |
+| `GET /clawd/rug-alert/{tokenAddr}` | $2.00 | Rug-alert webhook (30 days) |
+| `POST /webhook/extend` | $5.00 | Extend real-time webhook subscription |
+| `POST /sponsor/{address}` | $25/wk | Boosted leaderboard placement |
+
+## Onchain verification (Solidity)
+
+```solidity
+interface IMainStreetVerifier {
+  function requireMinScore(
+    bytes32 subject, uint8 minScore,
+    uint8 score, uint64 timestamp, uint64 nonce,
+    bytes calldata signature
+  ) external view returns (bool);
+}
+
+IMainStreetVerifier constant MS = IMainStreetVerifier(0x7397adb9713934c36d22aa54b4dbbcd70263592b);
+MS.requireMinScore(subject, 30, score, ts, nonce, sig);
+```
+
+Caller fetches `{subject, score, timestamp, nonce, signature}` from `GET /api/agent/attestation/{address}`, passes inline as tx calldata. No oracle subscription, no upkeep, ~$0.00003 in gas.
+
+## npm package
+
+```bash
+npm i @raskhaaa/mainstreet-oracle viem
+
+import { requireMinScore } from '@raskhaaa/mainstreet-oracle/verifier';
+import * as viem from 'viem';
+
+// throws if score < 30 or signature invalid
+const score = await requireMinScore('0xAgentAddr', 30, viem);
+```
+
+## EIP-712 schema
+
+```
+Attestation(
+  string version,         // "mainstreet-v1"
+  string subjectType,     // "agent-onchain"
+  bytes32 subject,        // sha256(toLowerCase(address))
+  uint8 score,            // 0-100
+  uint64 timestamp,       // unix seconds, ≤24h fresh
+  address operator,       // 0xAC3ca7c5d3cDD7702fd08F9C4C28dAA22296aDa9
+  uint64 nonce
+)
+```
+
+Domain: `{ name: "MainStreet", version: "1", chainId: 8453 }`.
+
+## Live coverage (June 2026)
+
+- 847 Base AI agents indexed
+- 4,811 Virtuals agents cross-referenced
+- 153,073 x402 settlements tracked
+- $24,562 USDC volume seen
+- 1,513 unique buyers
+- 16 ERC-8004 registered agents in our index
+- Top 10 scores published onchain weekly via EAS (composable signal)
diff --git a/mainstreet/scripts/mainstreet-attestation.sh b/mainstreet/scripts/mainstreet-attestation.sh
new file mode 100644
index 0000000000..32260bdfd7
--- /dev/null
+++ b/mainstreet/scripts/mainstreet-attestation.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# mainstreet-attestation.sh — fetch EIP-712 signed attestation (free)
+set -euo pipefail
+[ -z "${1:-}" ] && { echo "usage: mainstreet-attestation.sh <0x-address>"; exit 1; }
+curl -sS "https://avisradar-production.up.railway.app/api/agent/attestation/$1"
diff --git a/mainstreet/scripts/mainstreet-audit-batch.sh b/mainstreet/scripts/mainstreet-audit-batch.sh
new file mode 100644
index 0000000000..a54c91681c
--- /dev/null
+++ b/mainstreet/scripts/mainstreet-audit-batch.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# mainstreet-audit-batch.sh — bulk audit up to 10 addresses ($1 USDC via x402)
+# usage: pass addresses as args. needs x402 wallet env (AGENT_PRIVATE_KEY).
+set -euo pipefail
+[ $# -lt 1 ] && { echo "usage: mainstreet-audit-batch.sh <addr1> [addr2] ..."; exit 1; }
+ADDRS=$(printf '"%s",' "$@" | sed 's/,$//')
+echo "POST https://avisradar-production.up.railway.app/api/agent/audit-batch"
+echo "Body: {\"addresses\":[$ADDRS]}"
+echo "Cost: \$1 USDC via x402. Sign with @x402/axios or x402-axios v1."
diff --git a/mainstreet/scripts/mainstreet-canonical.sh b/mainstreet/scripts/mainstreet-canonical.sh
new file mode 100644
index 0000000000..0cfe4e888f
--- /dev/null
+++ b/mainstreet/scripts/mainstreet-canonical.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# mainstreet-canonical.sh — unified identity (basename + ERC-8004 + agent.json + tier)
+set -euo pipefail
+[ -z "${1:-}" ] && { echo "usage: mainstreet-canonical.sh <0x-address>"; exit 1; }
+curl -sS "https://avisradar-production.up.railway.app/api/agent/canonical-id/$1"
diff --git a/mainstreet/scripts/mainstreet-score.sh b/mainstreet/scripts/mainstreet-score.sh
new file mode 100644
index 0000000000..33ef363097
--- /dev/null
+++ b/mainstreet/scripts/mainstreet-score.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# mainstreet-score.sh — fetch free MainStreet reputation score for any Base address
+set -euo pipefail
+[ -z "${1:-}" ] && { echo "usage: mainstreet-score.sh <0x-address>"; exit 1; }
+curl -sS "https://avisradar-production.up.railway.app/api/agent/score/$1"
diff --git a/mainstreet/scripts/mainstreet-verify.sh b/mainstreet/scripts/mainstreet-verify.sh
new file mode 100644
index 0000000000..d143f8dd81
--- /dev/null
+++ b/mainstreet/scripts/mainstreet-verify.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# mainstreet-verify.sh — verify a signed attestation server-side
+# usage: pipe the attestation JSON in, optionally with MIN_SCORE env var
+set -euo pipefail
+MIN_SCORE="${MIN_SCORE:-0}"
+ATT_JSON="${1:-$(cat)}"
+PAYLOAD=$(echo "$ATT_JSON" | jq '.payload')
+SIG=$(echo "$ATT_JSON" | jq -r '.signature')
+curl -sS -X POST "https://avisradar-production.up.railway.app/api/agent/verify" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --argjson p "$PAYLOAD" --arg s "$SIG" --arg m "$MIN_SCORE" '{payload:$p,signature:$s,minScore:($m|tonumber)}')"

From f21aca2632fb8f27a48c8526d75f2e014fe775db Mon Sep 17 00:00:00 2001
From: Philippe <philpof98@gmail.com>
Date: Sat, 6 Jun 2026 09:40:48 +0200
Subject: [PATCH 2/2] mainstreet: add README index row + reference docs

- README.md: add MainStreet row next to erc-8004 in the providers table.
- references/api.md: REST surface and the x402-paid attestation endpoint.
- references/verifier.md: onchain verification flow + verifier ABI.
- references/scoring.md: how the 0-100 score is built and how to use it
  responsibly at different payment sizes.

Complements the existing SKILL.md and scripts. Site:
https://avisradar-production.up.railway.app/mainstreet
---
 README.md                         |  1 +
 mainstreet/references/api.md      | 56 +++++++++++++++++++++++++++++++
 mainstreet/references/scoring.md  | 44 ++++++++++++++++++++++++
 mainstreet/references/verifier.md | 45 +++++++++++++++++++++++++
 4 files changed, 146 insertions(+)
 create mode 100644 mainstreet/references/api.md
 create mode 100644 mainstreet/references/scoring.md
 create mode 100644 mainstreet/references/verifier.md

diff --git a/README.md b/README.md
index 5032fce8d1..511a642269 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ Bankr Skills equip builders with plug-and-play tools to build more powerful agen
 | [Endaoment](https://endaoment.org) | [endaoment](endaoment/) | Charitable donations on-chain. Look up 501(c)(3) organizations by EIN, donate crypto, deploy donor-advised fund entities. |
 | [ENS](https://ens.domains) | [ens-primary-name](ens-primary-name/) | ENS name management. Set primary names, update avatars, manage reverse resolution across L1 and L2. |
 | [8004.org](https://8004.org) | [erc-8004](erc-8004/) | On-chain agent identity registry. ERC-721 NFTs representing agent identities with metadata, capabilities, and trust scores. |
+| [MainStreet](https://avisradar-production.up.railway.app/mainstreet) | [mainstreet](mainstreet/) | Onchain reputation oracle for AI agents on Base. SAFE / CAUTION / BLOCK + 0-100 score before any agent-to-agent payment. EIP-712 signed attestations verifiable onchain. Indexes x402 settlements, ERC-8004 feedback, Bazaar listings. |
 | [Coinbase](https://onchainkit.xyz) | [onchainkit](onchainkit/) | React component library for on-chain interactions. Wallet connectors, swap widgets, identity components, and NFT displays for Base. |
 | [qrcoin](https://qrcoin.fun) | [qrcoin](qrcoin/) | QR code auction game. Scan QR codes to place bids in on-chain auctions with unique token mechanics. |
 | [Veil Cash](https://veil.cash) | [veil](veil/) | Privacy-preserving transactions. Deposit into shielded pools, perform ZK withdrawals, manage private transfers. |
diff --git a/mainstreet/references/api.md b/mainstreet/references/api.md
new file mode 100644
index 0000000000..e043d75112
--- /dev/null
+++ b/mainstreet/references/api.md
@@ -0,0 +1,56 @@
+# MainStreet API Reference
+
+Base URL: `https://avisradar-production.up.railway.app`
+
+## Free endpoints
+
+### `GET /api/agent/score/:address`
+
+Returns the cached reputation score for any Base address.
+
+Response: see `SKILL.md` for the full shape.
+
+Rate limit: 1000+ calls per IP per day.
+
+### `GET /api/agent/leaderboard?limit=N`
+
+Returns the top N agents by score across all indexed ecosystems
+(x402 Bazaar, ERC-8004, Virtuals, Clanker, OpenClawd).
+
+### `GET /api/agent/coverage`
+
+Returns aggregate stats: total indexed, total volume, network breakdown.
+
+### `GET /api/agent/by-category/:category`
+
+Returns agents within a category tag (`video`, `maps-travel`, `defi`, etc.).
+
+## x402-paid endpoints
+
+### `POST /api/agent/attest`
+
+Returns an EIP-712 signed attestation for the queried address. The buyer can
+verify the signature onchain at the MainStreet verifier contract to prove the
+score they relied on at decision time.
+
+Price: $0.05 USDC per call on Base.
+
+Body:
+
+```json
+{ "address": "0x...", "context": "x402-prepay" }
+```
+
+Response:
+
+```json
+{
+  "domain": { "name": "MainStreet", "version": "1", "chainId": 8453, "verifyingContract": "0x7397adb9713934c36d22aa54b4dbbcd70263592b" },
+  "types": { "Attestation": [{ "name": "subject", "type": "address" }, { "name": "score", "type": "uint8" }, { "name": "verdict", "type": "uint8" }, { "name": "issuedAt", "type": "uint64" }, { "name": "nonce", "type": "uint256" }] },
+  "primaryType": "Attestation",
+  "message": { "subject": "0x...", "score": 76, "verdict": 0, "issuedAt": 1717650000, "nonce": "0x..." },
+  "signature": "0x..."
+}
+```
+
+Verdict enum: `0 = SAFE`, `1 = CAUTION`, `2 = BLOCK`.
diff --git a/mainstreet/references/scoring.md b/mainstreet/references/scoring.md
new file mode 100644
index 0000000000..84aa3ba189
--- /dev/null
+++ b/mainstreet/references/scoring.md
@@ -0,0 +1,44 @@
+# Scoring model
+
+The score is a 0-100 number summarizing the onchain track record of an address.
+The verdict (SAFE / CAUTION / BLOCK) is derived from the score plus a small
+number of hard signals (denylist match, sniper pattern, smart-wallet vs EOA,
+deployer reputation).
+
+## Inputs
+
+- **Settlements** — count and USDC volume of x402 (or equivalent) payments
+  received, weighted by recency.
+- **ERC-8004 feedback** — signed reputation events from other agents.
+- **Health probes** — periodic latency and uptime samples against the seller's
+  resource path.
+- **Identity proofs** — smart-wallet (4337 / proxy), claimed ENS / DID,
+  domain binding.
+- **Launch context** — for Virtuals / Clanker / OpenClawd tokens: developer
+  commitment level, tokenomics status, age, holder count, mindshare.
+
+## Outputs
+
+```
+score        0-100
+trustShield  green | yellow | red
+verdict      SAFE | CAUTION | BLOCK
+proofs       array of weighted proof objects
+trustLevel   tier 0-4 (NEW / EARLY / ACTIVE / VERIFIED / ELITE)
+```
+
+## Why 0-100
+
+The number is intentionally NOT a probability. It is a relative rank inside
+the indexed population (currently 883 agents). A SAFE verdict means the agent
+is in the top-decile of its category by track record, not that it's
+mathematically guaranteed not to rug.
+
+## How to use it correctly
+
+- For low-value calls ($0.001-$0.01): trust the free verdict.
+- For meaningful payments ($1+): pull the signed attestation and verify
+  onchain. The $0.05 attestation fee is rounding compared to the loss of
+  paying a rug.
+- For high-value or recurring relationships: combine the score with the
+  agent's own signed receipts (`/api/agent/receipts/:address`).
diff --git a/mainstreet/references/verifier.md b/mainstreet/references/verifier.md
new file mode 100644
index 0000000000..9e4e850158
--- /dev/null
+++ b/mainstreet/references/verifier.md
@@ -0,0 +1,45 @@
+# Onchain Verifier
+
+The MainStreet verifier is a stateless contract that recovers the EIP-712
+signature on an attestation and confirms it was signed by the canonical
+MainStreet oracle key.
+
+**Address:** `0x7397adb9713934c36d22aa54b4dbbcd70263592b`
+**Network:** Base mainnet (chainId 8453)
+**Source:** https://github.com/philpof102-svg/mainstreet/blob/main/contracts/MainStreetVerifier.sol
+
+## Verification flow
+
+1. Buyer calls `POST /api/agent/attest { address, context }`.
+2. Buyer receives a signed EIP-712 attestation (see `api.md`).
+3. Buyer (or anyone, later) calls `verify(message, signature)` on the
+   verifier contract.
+4. The contract returns `true` if the signature recovers to the MainStreet
+   oracle address.
+
+```solidity
+function verify(
+  address subject,
+  uint8 score,
+  uint8 verdict,
+  uint64 issuedAt,
+  uint256 nonce,
+  bytes calldata signature
+) external view returns (bool);
+```
+
+## Why this matters
+
+The attestation is third-party-verifiable without trusting MainStreet's API.
+If a buyer agent paid an x402 seller based on a SAFE attestation and that
+seller later turned out to be malicious, the buyer has cryptographic proof of
+the verdict it relied on at the moment of payment.
+
+This is the same pattern used by traditional rating agencies — except the
+"rating" is queryable in 5 ms and verifiable by a smart contract.
+
+## Anti-staleness
+
+Each attestation includes `issuedAt` (unix seconds) and a `nonce`. Consumers
+should reject attestations older than their tolerance window (recommended:
+60 seconds for live agent flows).