{
  "markdown": "# Vouch\n\n[![CI](https://github.com/notifuturo/vouch/actions/workflows/ci.yml/badge.svg)](https://github.com/notifuturo/vouch/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](./LICENSE)\n[![x402](https://img.shields.io/badge/pay-x402%20·%20USDC-5eead4.svg)](https://x402.org)\n[![Cloudflare Workers](https://img.shields.io/badge/runs%20on-Cloudflare%20Workers-f38020.svg)](https://workers.cloudflare.com)\n[![Live](https://img.shields.io/badge/demo-vouch.futuronoti.workers.dev-2563eb.svg)](https://vouch.futuronoti.workers.dev)\n\n**A per-call payment trust & reputation API for AI agents — monetized over [x402](https://x402.org).**\n\nWhen an autonomous agent is about to pay a merchant, API, or counterparty, it\nasks Vouch one question first: *is this safe to pay?* Vouch returns an\nexplainable trust score, and charges a fraction of a cent per call in USDC — no\naccounts, no API keys, no Stripe. Billing is the x402 protocol itself.\n\n## Why\n\nThe agentic-commerce rails (Coinbase x402, AWS, Visa, Mastercard, Agnic) are\nbeing built by giants. The **governance layer** — *should this agent trust this\ncounterparty with money?* — is the named #1 blocker to autonomous spend and is\nwide open. Vouch is a thin, self-serve pick-and-shovel on top of those rails.\n\nEvery call makes the product better: checks and community reports accrete into a\nreputation dataset that compounds with usage — the moat a bootstrapped team can\nactually build.\n\n## How it works\n\n```\nagent ──POST /v1/check { target }──▶  x402 paywall (402 → pay USDC → retry)\n                                          │\n                                          ▼\n                          ┌─────────── scoring engine ───────────┐\n                          │ transport · domain heuristics ·       │\n                          │ threat feed · reputation (D1)         │\n                          └───────────────────────────────────────┘\n                                          │\n                            { score, risk, reasons[] }\n```\n\nScoring is a weighted average of independent **signals**, with a safety\noverride: any single hard-negative signal (e.g. a threat-feed hit) caps the\noverall score so one strong red flag can't be averaged away.\n\n| Signal | Weight | Source |\n|--------|--------|--------|\n| `threat_feed` | 3 | [URLhaus](https://urlhaus.abuse.ch/) host list (`THREAT_FEED_URL`), cached, fails open |\n| `reputation` | 2 | Vouch's own accumulating D1 data (the moat) |\n| `transport` | 1.5 | HTTPS / valid host |\n| `domain_heuristics` | 1 | Punycode, raw IPs, abuse-prone TLDs, etc. |\n\n## Use it from your agent\n\nVouch is a real MCP server, an x402-paid HTTP API, and a tiny SDK — pick whichever\nfits your stack. Nothing needs an account or API key.\n\n### MCP (free tools, works in any MCP client)\n\nPoint your client at the Streamable-HTTP endpoint — it exposes `vouch_score` and\n`vouch_report`, and ships model-facing `instructions` so the agent knows to check a\ncounterparty **before** it pays:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"vouch\": { \"type\": \"streamable-http\", \"url\": \"https://vouch.futuronoti.workers.dev/mcp\" }\n  }\n}\n```\n\nFor clients that only speak stdio, bridge it with `npx mcp-remote https://vouch.futuronoti.workers.dev/mcp`.\nVouch is also listed in the [official MCP registry](https://registry.modelcontextprotocol.io)\nas `io.github.notifuturo/vouch`.\n\n### Free HTTP (curl)\n\n```bash\ncurl -s https://vouch.futuronoti.workers.dev/v1/score \\\n  -H 'content-type: application/json' -d '{\"target\":\"https://some-merchant.com\"}'\n# → {\"target\":\"...\",\"host\":\"some-merchant.com\",\"score\":91,\"risk\":\"low\"}\n```\n\n### Gate a payment with the SDK (one line)\n\n```ts\nimport { assertTrusted } from \"vouch-sdk\";\n\nawait assertTrusted(\"https://some-merchant.com\", { minScore: 75 }); // free; throws if risky\nawait payTheMerchant();\n```\n\nThe paid `POST /v1/check` adds the explainable `reasons`, weighted `signals`, and a\nsigned Ed25519 **attestation** (keep it as proof of due diligence). See\n[`examples/buyer.ts`](./examples/buyer.ts) for the full x402 pay-and-retry loop and\n[`sdk/`](./sdk) for the client.\n\n## Endpoints\n\n| Method & path | Cost | Description |\n|---------------|------|-------------|\n| `POST /v1/check` | x402 (USDC) | Full verdict → `{ score, risk, reasons, signals, attestation }` (signed Ed25519 receipt) |\n| `POST /v1/score` | free (rate-limited) | Score + risk only → `{ score, risk }`. Pay `/v1/check` for the *reasons* |\n| `GET /v1/attestation/pubkey` | free | Ed25519 public key (JWK) to verify a `/v1/check` attestation |\n| `POST /v1/report` | free | Submit a `flag` or `vouch` for a host |\n| `GET /v1/stats` | free | Aggregate reputation totals (hosts, checks, flags, vouches) |\n| `POST /mcp` | free | MCP Streamable-HTTP server (`vouch_score`, `vouch_report` tools) |\n| `GET /health` | free | Liveness |\n| `GET /` | free | Service info (HTML landing for browsers) |\n\nCORS is open (`*`) and the x402 payment headers are exposed, so browser-hosted\nagents can preflight and complete the pay/retry flow.\n\n### Reading `/v1/report` (abuse model)\n\n`POST /v1/report` is **free and unauthenticated by design** — anyone can submit a\n`flag` or `vouch` for a host, so the raw `flags`/`vouches` counts are *community\nsignals, not ground truth*. Abuse is contained by:\n\n- **Rate limiting** — 10 reports per 60s per client IP (Cloudflare Rate Limiting, fails closed).\n- **Reporter-standing weighting** — each counted report contributes a *weighted* amount\n  (not a flat +1) based on the reporting source's tenure: a brand-new or anonymous source\n  counts at `0.3`, ramping to `1.0` only after ~7 days of sustained reporting. The scoring\n  signal uses these weighted totals, so spinning up fresh sybil identities buys far less\n  influence. A source can also move a given host's counter at most once per 24h (per-source\n  de-dup); raw counts are still logged for audit.\n- **Poisoning resistance in scoring** — community `reputation` is a *non-authoritative*\n  signal: it can lower a score but **cannot, on its own, force a `critical` verdict**.\n  Only objective signals (threat feeds, transport) can hard-cap the score. So a burst\n  of anonymous flags can't unilaterally brand a legitimate counterparty as unsafe.\n- **Bounded input** — `target`/`reason`/`reporter` are length-capped before storage.\n\nTreat `/v1/stats` and report counts as a crowd-sourced prior that *informs* the paid\nverdict, not as an authoritative blocklist.\n\n## Stack ($0 to run)\n\nTypeScript · [Hono](https://hono.dev) · Cloudflare Workers (free tier) ·\nD1 (free SQLite) · `@x402/*` v2 · public facilitator at `x402.org/facilitator`.\n\n**Live on Base mainnet** (`X402_NETWORK=base`, real USDC, `$0.01`/call). For local\ndevelopment, set `X402_NETWORK=base-sepolia` and fund a throwaway wallet from the\nfree [Circle faucet](https://faucet.circle.com). The live network and price are\nauthoritatively advertised at [`/.well-known/x402`](https://vouch.futuronoti.workers.dev/.well-known/x402).\n\n## Develop\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\n\ncp .dev.vars.example .dev.vars   # set PAY_TO_ADDRESS (your testnet wallet)\nwrangler d1 create vouch         # paste database_id into wrangler.toml\nnpm run db:init                  # apply schema locally\nnpm run dev                      # local Worker\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 7341,
  "sha": "1b9a769872e9a5f655a51e4b0e5253843c1c1921f3fcb464f6aaebd33d37d3db",
  "repo_slug": "notifuturo/vouch",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_notifuturo_vouch_3a6ba6dd/readme"
}