@forgemeshlabs/x402-notary-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeMesh Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# x402 Notary — Cryptographic Receipts for AI Outputs
+
+*A [ForgeMesh Labs](https://forgemesh.io) product — the notary of the x402 agent economy.*
+
+**Prove what your AI said, when it said it, and which model said it.**
+
+Every AI output is just text. There's no proof a specific model produced a specific response at a specific time — and as agents start hiring other agents, that trust gap gets expensive. x402 Notary closes it: submit any inference, pay **$0.001** in USDC (automatic, via [x402](https://x402.org) on Base — no API key, no account), and get back a **signed, timestamped, chain-anchored receipt** that anyone can verify, free, forever.
+
+> **We notarize the hash, not your secrets.** Your prompt and response are hashed and signed — never stored. Private signed receipts, publicly anchored by batch root on Base.
+
+## Quick start (Claude Desktop / Claude Code / any MCP client)
+
+```json
+{
+  "mcpServers": {
+    "x402-notary": {
+      "command": "npx",
+      "args": ["-y", "@forgemeshlabs/x402-notary-mcp"],
+      "env": {
+        "WALLET_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+`WALLET_PRIVATE_KEY` is a **dedicated low-balance Base wallet** for x402 micropayments — never your primary wallet. $1 of USDC notarizes 1,000 outputs.
+
+**Verification needs no wallet at all.** Skip the `env` block entirely and you can still verify receipts, inspect attestations, and read live stats.
+
+## Tools
+
+| Tool | Cost | What it does |
+|---|---|---|
+| `notarize_inference` | $0.001 | Signed receipt for one `{prompt, response, model_id}` |
+| `notarize_batch` | $0.005 | Up to 20 receipts in one call — built for audit trails |
+| `verify_attestation` | **free** | Check any receipt: signature, content hash, Merkle proof |
+| `get_receipt` | **free** | Fetch the public proof material for an attestation |
+| `notary_stats` | **free** | Live volume, top models, anchored batches |
+| `notary_pubkey` | **free** | The notary's Ed25519 key — verify receipts fully offline |
+
+## What a receipt proves
+
+When you notarize an inference you get an attestation:
+
+```json
+{
+  "attestation_id": "att_64d22f5f5c95d0e759ad54dc",
+  "content_hash": "sha256 of {prompt, response, model_id, timestamp}",
+  "signature": "Ed25519 — verifiable offline against the public notary key",
+  "notarized_at": "2026-07-03T02:47:11.000Z",
+  "anchor": { "status": "sealed", "merkle_root": "…", "proof": ["…"] }
+}
+```
+
+That's proof of three things:
+
+1. **Existence** — this exact content existed at this exact time.
+2. **Integrity** — change one character of the prompt or response and verification fails.
+3. **Independence** — signatures verify offline with the published key; Merkle roots anchor batches on Base. You don't have to trust the notary's word after the fact.
+
+## Verify anything, free, from anywhere
+
+Any agent (or human, or CI job) can check a receipt before acting on the output behind it:
+
+```bash
+curl -s https://notary.forgemesh.io/api/verify \
+  -H 'content-type: application/json' \
+  -d '{"attestation_id":"att_…","prompt":"…","response":"…","model_id":"openai/gpt-5"}'
+```
+
+`"valid": true` means the content matches the notarized hash **and** the notary's Ed25519 signature checks out. Tampered content is rejected with the exact failing check.
+
+## When should an agent notarize?
+
+Not every call — the outputs that matter:
+
+- **Agent-to-agent handoffs** — prove what you passed downstream came from this model, unmodified
+- **Paid deliverables** — research, reports, recommendations someone is paying for
+- **Compliance & audit trails** — decisions that affect money, legal exposure, or reputation
+- **Dispute prevention** — "this is exactly what was generated, at exactly this time"
+- **Marketplace reputation** — build a public, verifiable reliability trail for your agent or service
+
+Casual chat and scratchpad reasoning don't need receipts. Externalized outputs do.
+
+## Privacy, by design
+
+- Raw prompts, responses, and metadata are **not persisted** — the notary computes the hash, signs it, and discards the content.
+- Receipts contain proof material only: hash, signature, timestamps, model id, Merkle proof.
+- Only Merkle **batch roots** are anchored on-chain. Your content never touches a public chain.
+- Verification works by *you* supplying your original content — the notary can't reveal what it never kept.
+
+## How payment works
+
+No signup, no API key, no subscription. The first request returns an HTTP 402 challenge; your MCP client signs a USDC payment authorization (EIP-3009) and retries. Settlement happens on Base in seconds and the receipt lands in the same response — including the payment transaction hash under `_payment`.
+
+## Direct API
+
+Prefer raw HTTP? The full agent-readable surface:
+
+- `https://notary.forgemesh.io/llms.txt` — one-page summary for agents
+- `https://notary.forgemesh.io/openapi.json` — OpenAPI 3.1 with x402 payment metadata
+- `https://notary.forgemesh.io/.well-known/x402.json` — x402 discovery manifest
+
+## FAQ
+
+**Is my prompt stored anywhere?** No. The hash is computed, signed, and the raw text is discarded. This is the default and only mode.
+
+**Do I need an account or API key?** No. x402 payments are the only credential.
+
+**What does verification cost?** Nothing, for anyone, forever. Charging to verify would defeat the point of a trust primitive.
+
+**What chain and token?** USDC on Base mainnet (`eip155:8453`).
+
+**Can I verify receipts without contacting the notary?** Yes — fetch the Ed25519 public key once (`notary_pubkey`) and verify signatures offline.
+
+**Why "x402 Notary"?** [x402](https://x402.org) is the open protocol that lets AI agents pay for services in USDC over plain HTTP — and this is its notary: the attestation layer agents use to prove and verify each other's outputs before money or reputation moves on them.
+
+---
+
+Built by [ForgeMesh Labs](https://forgemesh.io) · Powered by the [x402 protocol](https://x402.org) · MIT License

package/index.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+"use strict";
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { CallToolRequestSchema, ListToolsRequestSchema } = require("@modelcontextprotocol/sdk/types.js");
+const { x402Client, x402HTTPClient } = require("@x402/core/client");
+const { ExactEvmScheme } = require("@x402/evm/exact/client");
+const { toClientEvmSigner } = require("@x402/evm");
+const { privateKeyToAccount } = require("viem/accounts");
+const { createPublicClient, http } = require("viem");
+const { base } = require("viem/chains");
+
+const VERSION = "0.1.0";
+const BASE_URL = (process.env.NOTARY_BASE_URL || "https://notary.forgemesh.io").replace(/\/$/, "");
+const BASE_RPC_URL = process.env.BASE_RPC_URL || "https://mainnet.base.org";
+
+const RECORD_PROPS = {
+  prompt: { type: "string", description: "The exact prompt/input that was sent to the model" },
+  response: { type: "string", description: "The exact model output you want a receipt for" },
+  model_id: { type: "string", description: "Model identifier, e.g. 'openai/gpt-5' or 'claude-fable-5'" },
+  client_timestamp: {
+    type: "string",
+    description: "Optional ISO-8601 time the inference ran. Included in the content hash if provided.",
+  },
+};
+
+const TOOLS = [
+  {
+    name: "notarize_inference",
+    description:
+      "Get a cryptographic receipt for one AI inference. Returns a signed Ed25519 attestation, sha256 content hash, and Merkle chain-anchor status for {prompt, response, model_id}. The notary does NOT store your prompt or response — only the hash is retained. Costs $0.001 USDC via x402 (requires WALLET_PRIVATE_KEY).",
+    inputSchema: {
+      type: "object",
+      properties: RECORD_PROPS,
+      required: ["prompt", "response", "model_id"],
+    },
+  },
+  {
+    name: "notarize_batch",
+    description:
+      "Notarize up to 20 AI inferences in one call — one signed attestation per record. Ideal for audit trails and agent pipelines. Costs $0.005 USDC via x402 (requires WALLET_PRIVATE_KEY).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        records: {
+          type: "array",
+          description: "1-20 records of {prompt, response, model_id, client_timestamp?}",
+          items: { type: "object", properties: RECORD_PROPS, required: ["prompt", "response", "model_id"] },
+          minItems: 1,
+          maxItems: 20,
+        },
+      },
+      required: ["records"],
+    },
+  },
+  {
+    name: "verify_attestation",
+    description:
+      "FREE — verify any attestation issued by the notary. Supply the attestation_id plus either the original content ({prompt, response, model_id}) or its content_hash. Returns the Ed25519 signature check, hash comparison, and a Merkle inclusion proof once the batch is sealed. No wallet needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        attestation_id: { type: "string", description: "Attestation id (att_…) from a receipt" },
+        ...RECORD_PROPS,
+        content_hash: {
+          type: "string",
+          description: "Alternative to supplying full content: the sha256 content hash to compare directly",
+        },
+      },
+      required: ["attestation_id"],
+    },
+  },
+  {
+    name: "get_receipt",
+    description:
+      "FREE — fetch the public receipt for an attestation: content hash, model, timestamps, Ed25519 signature, and Merkle anchor proof. Raw prompt/response are never stored, so receipts contain proof material only. No wallet needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        attestation_id: { type: "string", description: "Attestation id (att_…)" },
+      },
+      required: ["attestation_id"],
+    },
+  },
+  {
+    name: "notary_stats",
+    description:
+      "FREE — live aggregate stats: total notarizations, 24h volume, top models by attestation count, sealed/anchored Merkle batches. No wallet needed.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "notary_pubkey",
+    description:
+      "FREE — the notary's Ed25519 public key (base64, raw 32 bytes) for fully offline signature verification. No wallet needed.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+function buildHttpClient() {
+  const key = process.env.WALLET_PRIVATE_KEY;
+  if (!key) {
+    throw new Error(
+      "WALLET_PRIVATE_KEY is not set. Notarization costs $0.001 USDC via x402 — set a dedicated low-balance Base wallet private key (never your primary wallet). Verification tools work without it."
+    );
+  }
+  const pk = key.startsWith("0x") ? key : "0x" + key;
+  const account = privateKeyToAccount(pk);
+  const coreClient = new x402Client().register("eip155:*", new ExactEvmScheme(toClientEvmSigner(account)));
+  return { httpClient: new x402HTTPClient(coreClient), account };
+}
+
+// x402 derives EIP-3009 validity windows from Date.now; choose a timestamp
+// valid for both Base block time and facilitator wall-clock checks.
+async function createChainTimedPaymentPayload(httpClient, paymentRequired) {
+  try {
+    const publicClient = createPublicClient({ chain: base, transport: http(BASE_RPC_URL) });
+    const block = await publicClient.getBlock();
+    const chainNow = Number(block.timestamp);
+    const originalNow = Date.now;
+    const localNow = Math.floor(originalNow() / 1000);
+    const timeout = Number(paymentRequired.accepts?.[0]?.maxTimeoutSeconds || 300);
+    const lowerBound = localNow + 30 - timeout;
+    const upperBound = chainNow + 600;
+    const signingNow = Math.min(Math.max(chainNow, lowerBound), upperBound);
+    Date.now = () => signingNow * 1000;
+    try {
+      return await httpClient.createPaymentPayload(paymentRequired);
+    } finally {
+      Date.now = originalNow;
+    }
+  } catch (_) {
+    return httpClient.createPaymentPayload(paymentRequired);
+  }
+}
+
+async function freeFetch(path, init) {
+  const res = await fetch(BASE_URL + path, init);
+  const raw = await res.text();
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (_) {
+    data = { raw: raw.slice(0, 500) };
+  }
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${JSON.stringify(data).slice(0, 300)}`);
+  return data;
+}
+
+async function paidPost(ctx, path, body) {
+  const { httpClient } = ctx;
+  const url = BASE_URL + path;
+  const init = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) };
+  const res = await fetch(url, init);
+
+  if (res.status === 402) {
+    let challengeBody;
+    try {
+      challengeBody = await res.clone().json();
+    } catch (_) {}
+    const paymentRequired = httpClient.getPaymentRequiredResponse((name) => res.headers.get(name), challengeBody);
+    const paymentPayload = await createChainTimedPaymentPayload(httpClient, paymentRequired);
+    const paidRes = await fetch(url, {
+      ...init,
+      headers: { ...init.headers, ...httpClient.encodePaymentSignatureHeader(paymentPayload) },
+    });
+    if (!paidRes.ok) {
+      const errBody = await paidRes.text().catch(() => paidRes.statusText);
+      throw new Error(`HTTP ${paidRes.status}: ${errBody.slice(0, 200)}`);
+    }
+    const data = await paidRes.json();
+    try {
+      const settleResponse = httpClient.getPaymentSettleResponse((name) => paidRes.headers.get(name));
+      if (settleResponse && data && typeof data === "object" && !Array.isArray(data)) {
+        return { ...data, _payment: settleResponse };
+      }
+    } catch (_) {}
+    return data;
+  }
+
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => res.statusText);
+    throw new Error(`HTTP ${res.status}: ${errBody.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+async function main() {
+  let ctx;
+  function getPaymentContext() {
+    if (!ctx) ctx = buildHttpClient();
+    return ctx;
+  }
+
+  const server = new Server({ name: "x402-notary-mcp", version: VERSION }, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    try {
+      let data;
+      switch (name) {
+        case "notarize_inference":
+          data = await paidPost(getPaymentContext(), "/api/notarize", args);
+          break;
+        case "notarize_batch":
+          data = await paidPost(getPaymentContext(), "/api/notarize/batch", { records: args.records });
+          break;
+        case "verify_attestation":
+          data = await freeFetch("/api/verify", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(args),
+          });
+          break;
+        case "get_receipt":
+          data = await freeFetch(`/api/receipt/${encodeURIComponent(args.attestation_id)}`);
+          break;
+        case "notary_stats":
+          data = await freeFetch("/api/stats");
+          break;
+        case "notary_pubkey":
+          data = await freeFetch("/api/pubkey");
+          break;
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`x402-notary-mcp v${VERSION} ready — ${BASE_URL}`);
+}
+
+main().catch((e) => {
+  console.error("Fatal:", e.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@forgemeshlabs/x402-notary-mcp",
+  "version": "0.1.0",
+  "description": "The notary of the x402 agent economy, by ForgeMesh Labs. Cryptographic receipts for AI outputs: notarize any model inference with a signed Ed25519 attestation, sha256 content hash, and Merkle chain-anchor on Base — $0.001 per call via x402 USDC micropayments. Verification is free and needs no wallet. We notarize the hash, never your prompts.",
+  "main": "index.js",
+  "bin": {
+    "x402-notary-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "server.json",
+    "LICENSE"
+  ],
+  "mcpName": "io.github.forgemeshlabs/x402-notary-mcp",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "notary",
+    "ai-notarization",
+    "attestation",
+    "ai-provenance",
+    "cryptographic-receipt",
+    "verify-ai-output",
+    "audit-trail",
+    "ed25519",
+    "merkle-proof",
+    "usdc",
+    "base",
+    "micropayments",
+    "autonomous-agents",
+    "agent-trust"
+  ],
+  "author": "ForgeMesh Labs (https://forgemesh.io)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgemeshlabs/x402-notary-mcp.git"
+  },
+  "homepage": "https://notary.forgemesh.io",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "@x402/core": "^2.11.0",
+    "@x402/evm": "^2.11.0",
+    "viem": "^2.0.0"
+  }
+}

package/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.forgemeshlabs/x402-notary-mcp",
+  "description": "The notary of the x402 agent economy, by ForgeMesh Labs. Cryptographic receipts for AI outputs: signed Ed25519 attestations, sha256 content hashes, and Merkle chain-anchors on Base for $0.001 per inference via x402 USDC micropayments. Free verification, no wallet needed. We notarize the hash, never your prompts.",
+  "repository": {
+    "url": "https://github.com/forgemeshlabs/x402-notary-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@forgemeshlabs/x402-notary-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "WALLET_PRIVATE_KEY",
+          "description": "Dedicated low-balance Base wallet private key for x402 USDC micropayments ($1 notarizes 1,000 outputs). Optional — verification tools work without it. Never use your primary wallet.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}