Notarize Integration Guide

Cryptographic receipts for AI agent decisions — MCP server, x402 keyless path, AWS Bedrock AgentCore, and receipt verification. E2E validated 2026-09-16 (receipt nr_d9583861b8fb6ab620ce64bec8c14b73, Base block 51367733).

Part A — MCP Server Path (Claude Desktop)

Easiest path if you use Claude Desktop. No x402 wallet setup required — uses API key billing instead.

Step 1 — Install & configure the MCP server

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fairseal": {
      "command": "npx",
      "args": ["-y", "@fairseal/mcp-server"],
      "env": {
        "FAIRSEAL_API_KEY": "fsn_your_key_here"
      }
    }
  }
}

Save and restart Claude Desktop. To verify the server starts correctly, you can run it from your terminal:

# Expected output: [fairseal-mcp-server] ready on stdio — upstream https://api.fairseal.io
npx @fairseal/mcp-server

Press Ctrl+C to exit. In Claude Desktop, the MCP tools will appear in the tool list after restart.

Step 2 — Hash your input and decision (local, zero network)

Ask Claude:

"Hash this text with fairseal_hash_content: [the input your agent acted on]"

Note the returned sha256 — this is your input_hash.

"Hash this text with fairseal_hash_content: [the decision the agent made]"

Note that sha256 — this is your decision_hash.

Why hash locally? fairseal_hash_content is a pure local function — SHA-256 in the Node.js process. Your raw content never leaves your machine. Only the hash goes to FairSeal.

Step 3 — Notarize

"Call fairseal_notarize_decision with:
- agent_id: my-agent-v1
- input_hash: <from step 2>
- decision_hash: <from step 2>
- description: Approved loan application #4829"

Expected response (HTTP 201, status: "pending_anchor"):

{
  "receipt_id": "nr_d9583861b8fb6ab620ce64bec8c14b73",
  "leaf_hash": "94daa4c3250b46f2...",
  "verify_url": "https://api.fairseal.io/v1/notarize/nr_d9583861b8fb6ab620ce64bec8c14b73",
  "status": "pending_anchor",
  "created_at": "2026-09-16T02:12:51.970Z"
}

Step 4 — Fetch the receipt once anchored (free, ~2 min wait)

Wait ~2 minutes, then ask:

"Call fairseal_notarize_status with receipt_id: nr_d9583861b8fb6ab620ce64bec8c14b73"

Once status is anchored, you receive the Merkle proof and Base tx hash. See Part D for offline verification.

Part B — Direct x402 Path (no MCP, no signup)

For developers not using an MCP client. Pay $0.02 USDC on Base mainnet per call, no API key required. All 5 walkthrough steps below are validated against live endpoints (2026-09-16).

Step 2 — Set up wallet & x402 client

Get USDC on Base mainnet

• From Coinbase: withdraw USDC, select "Base" network
• Bridge: bridge.base.org (from Ethereum mainnet)
• Onramp: any exchange that supports Base direct withdrawal
• You need: ≥ $0.05 USDC (covers 2 calls + headroom) + ~$0.001 ETH for gas

Install

mkdir fairseal-notarize && cd fairseal-notarize
npm init -y
npm install @x402/fetch @x402/evm viem @fairseal/verify

Step 3 — Notarize ($0.02 USDC via x402)

Full example (notarize.mjs) — validated 2026-09-16

// notarize.mjs
import { createHash } from "node:crypto";
import { createWalletClient, createPublicClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";

// ─── Wallet setup ────────────────────────────────────────────
const key = process.env.BUYER_KEY;   // 0x<64-hex-private-key>
if (!key) { console.error("Set BUYER_KEY env var"); process.exit(1); }

const account = privateKeyToAccount(key);
const rpcUrl = "https://mainnet.base.org";
const pub = createPublicClient({ chain: base, transport: http(rpcUrl) });
const wal = createWalletClient({ account, chain: base, transport: http(rpcUrl) });
const signer = toClientEvmSigner({
  address: account.address,
  signTypedData: wal.signTypedData.bind(wal),
  readContract: pub.readContract.bind(pub),
});

// ─── x402 auto-pay client ────────────────────────────────────
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// ─── Hash content locally (raw content never sent) ──────────
const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex");

const agentInput    = "Should we approve loan application #4829?";
const agentDecision = "Approve. Debt-to-income ratio within policy limits.";
const input_hash    = sha256(agentInput);
const decision_hash = sha256(agentDecision);

// ─── POST to x402 endpoint — auto-pays $0.02 USDC ───────────
const body = {
  schema: "agent_decision",
  payload_hash: decision_hash,
  metadata: {
    agent_id:      "my-agent-v1",
    decided_at:    new Date().toISOString(),
    input_hash,
    decision_hash,
    description:   "Loan approval decision",    // optional
    session_id:    "session-abc123",            // optional
    model:         "claude-fable-5",            // optional
    operator:      "FinAdvisorCo",              // optional
  }
};

console.log("Sending notarize request (will auto-pay $0.02 USDC on 402)...");
const response = await fetchWithPayment(
  "https://x402.fairseal.io/v1/notarize",
  { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }
);

if (response.status !== 201) {
  console.error("Notarize failed:", response.status, await response.text());
  process.exit(1);
}
const receipt = await response.json();
console.log("✓ receipt_id:", receipt.receipt_id);
console.log("  status:    ", receipt.status);       // pending_anchor
console.log("  verify_url:", receipt.verify_url);

export BUYER_KEY=0x<your-64-hex-private-key>
node notarize.mjs

Live 402 Challenge (verified 2026-09-16)

The server returns this when you POST without auth. @x402/fetch parses and handles it automatically:

{
  "x402Version": 2,
  "error": "Payment required",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "20000",                                      // $0.02 USDC (6-decimal)
    "asset":  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base mainnet
    "payTo":  "0xBd5eB5559f5Ac14475AC0C81b6735A4d9106ce28",
    "maxTimeoutSeconds": 300
  }]
}

Step 4 — Poll until anchored (free, ~2 min)

Add this after the notarize call in your script:

// ─── Poll until anchored (~2 min) ───────────────────────────
const receiptId = receipt.receipt_id;
let anchored = null;
for (let i = 0; i < 24; i++) {
  await new Promise(r => setTimeout(r, 15_000));  // wait 15s
  const r = await fetch(`https://api.fairseal.io/v1/notarize/${receiptId}`);
  anchored = await r.json();
  console.log(`poll ${i+1}: status=${anchored.status}`);
  if (anchored.status === "anchored") break;
}
if (anchored?.status !== "anchored") {
  console.error("Timeout: receipt did not anchor within 6 min. Try again later.");
  process.exit(1);
}
console.log("✓ Anchored at Base block", anchored.proof.anchor_block);
console.log("  tx:", anchored.proof.anchor_tx);

Step 5 — Verify (offline with @fairseal/verify v0.4.0)

// ─── Offline verification (add to same script after polling) ─
import { verifyMerklePath, verifyAnchor } from "@fairseal/verify";

// Step 5a: verify Merkle inclusion (pure local math, no network)
const proof = anchored.proof;
const leafOk = verifyMerklePath(proof.leaf_hash, proof.merkle_path, proof.merkle_root);
console.log("Merkle inclusion:", leafOk ? "✓ PASS" : "✗ FAIL");

// Step 5b: verify anchor is on Base mainnet (one RPC call to a node YOU trust)
//          v0.4.0 accepts the raw receipt directly — no manual field remapping
const result = await verifyAnchor(anchored, { rpcUrl: "https://mainnet.base.org" });
console.log("On-chain anchor:", result.valid ? "✓ PASS" : "✗ FAIL", result.errors);

Alternative: Browser verify (no code)

Open verify.fairseal.io, scroll to the "Notarize Receipt Lookup" section, paste your receipt_id (e.g. nr_d9583861b8fb6ab620ce64bec8c14b73) and click "Look Up".

Alternative: curl (quick sanity check)

# No auth required — free public lookup
curl -s "https://api.fairseal.io/v1/notarize/nr_d9583861b8fb6ab620ce64bec8c14b73" \
  | python3 -m json.tool | grep -E '"status"|"anchor_block"|"anchor_tx"'

    "status": "anchored",
    "anchor_block": 51367733,
    "anchor_tx": "0x63695b8dab26debe215f3ea49c805cbabaf3355c5b495f01afd2a397cc1fd91f",

Request body schema (reference)

POST https://x402.fairseal.io/v1/notarize    // x402 / keyless path
POST https://api.fairseal.io/v1/notarize     // API key path
Content-Type: application/json
Authorization: Bearer fsn_<key>              // key path only; omit for x402

{
  "schema":       "agent_decision",              // required — literal string
  "payload_hash": "<64-char lowercase sha256>",  // required
  "metadata": {
    "agent_id":      "<string>",                 // required
    "decided_at":    "<ISO-8601 UTC>",           // required
    "input_hash":    "<64-char lowercase sha256>",// required
    "decision_hash": "<64-char lowercase sha256>",// required
    "session_id":    "<string>",                 // optional
    "model":         "<string>",                 // optional
    "description":   "<string>",                // optional
    "operator":      "<string>"                 // optional
  }
}

All *_hash fields: 64-char lowercase hex (SHA-256). Unknown fields are rejected. Dates must be ISO-8601 UTC.

Part C — AWS Bedrock AgentCore Integration

AgentCore Payments implements the x402 protocol natively. When an AgentCore agent calls https://x402.fairseal.io/v1/notarize and receives HTTP 402, AgentCore:

1. Reads the PAYMENT-REQUIRED header (machine-readable JSON, x402Version 2)
2. Signs the payment via the configured Coinbase CDP or Stripe Privy embedded wallet
3. Retries the original request with the payment proof in the X-PAYMENT header
4. Receives HTTP 201 with the notarize receipt — no custom middleware needed

AgentCore Resource Model

Resource	Role
PaymentCredentialProvider	Holds wallet provider credentials (Coinbase or Stripe Privy)
Payment Manager	Orchestrates 402→sign→retry lifecycle
Payment Connector	Links manager to a credential provider
Payment Instrument	EMBEDDED_CRYPTO_WALLET — the wallet the agent spends from
Payment Session	Bounded spend window: maxSpendAmount + expiry

End-to-end flow from an AgentCore agent

Agent     → POST https://x402.fairseal.io/v1/notarize  {schema, payload_hash, metadata}
Server    → 402  PAYMENT-REQUIRED: {x402Version:2, amount:20000, network:"eip155:8453", ...}
AgentCore → signs EIP-3009 USDC authorization via Coinbase wallet
Agent     → POST (retry) + X-PAYMENT header
Server    → 201  { receipt_id: "nr_...", status: "pending_anchor", verify_url: "..." }

Zero custom code needed — AgentCore handles the 402→sign→retry loop. The agent receives the 201 JSON as if it were any ordinary HTTP API.

• AWS Bedrock AgentCore Payments (preview)
• Coinbase announcement

Part D — Receipt Anatomy, Verification, and the Delivered-vs-Verified Distinction

State	When	What it means	What it does NOT mean
Delivered	HTTP 201 returned	Request received, accepted, queued into next Merkle batch	The receipt is on-chain. You have not verified anything cryptographically.
Pending anchor	status: "pending_anchor"	Batch is building; anchors within ~2 min	Not yet verifiable offline
Anchored	status: "anchored"	Merkle root is written to the MerkleAnchor contract on Base	FairSeal's servers haven't been audited; verify the proof yourself
Cryptographically verified	You run verifyAnchor() locally	Merkle proof mathematically links your receipt to the on-chain root	Correctness of the decision — FairSeal proves provenance, not truth

Receipt anatomy (GET /v1/notarize/:id once anchored)

// GET https://api.fairseal.io/v1/notarize/nr_d9583861b8fb6ab620ce64bec8c14b73
{
  "receipt_id":   "nr_d9583861b8fb6ab620ce64bec8c14b73",
  "schema":       "agent_decision",
  "payload_hash": "49fe7a1ba52f86cd917b0732e319e8f4649e7456e51907fa996459e465549c4a",
  "metadata": {
    "agent_id":      "omi-r22-walkthrough",
    "decided_at":    "2026-09-16T02:12:51.715Z",
    "input_hash":    "c6ba86dbb8b2ecb6671a572cab7f50bf9be23e3813d243f32e49e0e24cf285bf",
    "decision_hash": "49fe7a1ba52f86cd917b0732e319e8f4649e7456e51907fa996459e465549c4a"
  },
  "created_at":   "2026-09-16T02:12:51.970Z",
  "status":       "anchored",
  "proof": {                                              // ← "proof", not "anchor"
    "leaf_hash":       "94daa4c3250b46f2...",            // SHA256(receipt_id + "||" + payload_hash)
    "leaf_formula":    "SHA256(receipt_id + '||' + payload_hash) — hex-as-text",
    "merkle_path":     [],                               // empty = single-receipt batch
    "merkle_root":     "94daa4c3250b46f2...",            // equals leaf_hash for single-item batch
    "batch_id":        "fairseal-notary-batch-...",
    "anchor_tx":       "0x63695b8dab26debe...",
    "anchor_block":    51367733,
    "anchor_chain_id": 8453,
    "anchor_contract": "0xEE09671Bbc6B932BF1461CAff360bfDD9bEA55ca"
  },
  "verification": {
    "leaf_recomputed_ok": true,
    "merkle_path_valid":  true,
    "anchored_onchain":   true,
    "verified":           true,
    "how_to_verify_independently": [...]
  }
}

Offline verification with @fairseal/verify

// verify.mjs — install: npm install @fairseal/verify@latest
import { verifyMerklePath, verifyAnchor } from "@fairseal/verify";

// Fetch the anchored receipt
const receipt = await fetch(
  "https://api.fairseal.io/v1/notarize/nr_d9583861b8fb6ab620ce64bec8c14b73"
).then(r => r.json());

const proof = receipt.proof;   // ← always receipt.proof

// Step 1 (offline, no network): Merkle inclusion check
//   Note: proof.merkle_path is a string[] of sibling hashes (pair-sorted).
//   For single-receipt batches this is [] and verifyMerklePath returns true trivially.
const inclusion = verifyMerklePath(proof.leaf_hash, proof.merkle_path, proof.merkle_root);
console.log("Merkle inclusion:", inclusion ? "✓ PASS" : "✗ FAIL");

// Step 2 (one RPC call to a Base node YOU trust): on-chain anchor confirmation
//   v0.4.0: pass the raw receipt directly — adapter auto-detects agent_decision schema
//   REQUIRED: provide rpcUrl pointing to a Base mainnet RPC you trust
const anchor = await verifyAnchor(receipt, { rpcUrl: "https://mainnet.base.org" });
console.log("On-chain anchor:", anchor.valid ? "✓ PASS" : "✗ FAIL");
// anchor.onChain.blockNumber, anchor.onChain.merkleRoot — on-chain values for audit

Manual verification (no library)

The receipt includes a step-by-step guide. For a single-receipt batch (proof.merkle_path: []):

1. Compute leaf = SHA256(receipt_id + "||" + payload_hash) — must match proof.leaf_hash
2. Since merkle_path is empty, merkle_root = leaf_hash (trivially)
3. Call getBatchRoot(proof.batch_id) on contract 0xEE09671… on Base — must equal 0x + proof.merkle_root
4. Or check proof.anchor_tx calldata on basescan.org

What FairSeal does NOT verify

• Correctness of the decision (a receipt is not a quality signal)
• Authenticity of inputs — input_hash is whatever you submitted
• PII endpoint: /v1/pii/detect responses are NOT Merkle-anchored. Do not use @fairseal/verify on PII responses.

Part E — Pricing & Keys Reference

Endpoint	Price	Auth	Receipt type
POST /v1/notarize	$0.02 USDC	API key (fsn_) OR x402 on Base	Merkle receipt (nr_…) — verifiable offline
GET /v1/notarize/{id}	Free	None	Receipt lookup (includes Merkle proof once anchored)
POST /v2/anchor	Per tier	API key (anck_) OR x402	Anchor only
GET /v2/anchor/{id}	Free	None	Anchor status
POST /v1/pii/detect	$0.001 USDC	x402	Scan result — not a Merkle receipt

API Keys

Environment variable	Key prefix	What it unlocks
FAIRSEAL_API_KEY	any	Universal fallback; used by MCP server if specific vars not set
FAIRSEAL_NOTARY_API_KEY	fsn_	Notarize service (/v1/notarize)
FAIRSEAL_ANCHOR_API_KEY	anck_	Anchor API v2 (/v2/anchor)

No key? Email hello@fairseal.io.

Hosts

Host	Purpose
api.fairseal.io	Key-authenticated calls; free GET receipt lookups
x402.fairseal.io	x402 keyless payment path; Anchor API v2
verify.fairseal.io	Browser-based receipt verifier (no code required)

Part F — Troubleshooting

400 "Path contains template placeholder"

{
  "error": "invalid_path",
  "self_correction": {
    "step1": "Compute SHA-256 of your payload first",
    "step2": "Submit: POST /v1/notarize with {schema, payload_hash, metadata}",
    "step3": "Poll: GET /v1/notarize/{actual_receipt_id}"   // ← use the nr_... value, not a template
  }
}

Cause: The agent used a literal {receipt_id} template string in the URL. Capture receipt.receipt_id from the POST 201 response and pass that value.

401/403 on /v1/notarize

• Key-auth → api.fairseal.io/v1/notarize + Authorization: Bearer fsn_…
• x402/keyless → x402.fairseal.io/v1/notarize — no auth header, let @x402/fetch pay automatically

402 "keeps returning" after payment

• USDC balance on Base is too low (need ≥ $0.02)
• x402 facilitator rejected the payment proof (wrong chain, wrong asset, expired signature)
• maxTimeoutSeconds (300s) exceeded — regenerate payment and retry

Check the X-PAYMENT-RESPONSE header for the rejection reason.

Receipt stays "pending_anchor" for > 5 minutes

Normal batch time is ~2 minutes. If persisting: contact hello@fairseal.io with your receipt_id.

verifyAnchor returns valid:false with empty errors

• Ensure you pass { rpcUrl: "https://mainnet.base.org" } as the second argument
• Use @fairseal/verify@latest (v0.4.0) — earlier versions require manual field remapping
• Ensure the receipt is "status": "anchored" before calling verifyAnchor

MCP key not recognized

Ensure FAIRSEAL_API_KEY or FAIRSEAL_NOTARY_API_KEY is in the MCP server env block (not in your shell — MCP servers run in a subprocess). Key prefix: fsn_.

"params can't be blank"

Ensure Content-Type: application/json is set and you're using the envelope format: {schema, payload_hash, metadata} — NOT flat fields.