Mercury · Cited Diff

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "description": "the page to re-fetch + diff (http/https)"
    },
    "prevHash": {
      "type": "string",
      "maxLength": 66,
      "description": "prior content hash (0x + 64 hex sha256) from an earlier MERCURY fetch/diff receipt. Gives a hash-only change-proof (changed? true/false). Use this OR prevText."
    },
    "prevText": {
      "type": "string",
      "maxLength": 262144,
      "description": "prior page text to diff against. Gives a full deterministic line-level diff (added/removed counts + unified-style hunk) on top of the change-proof. Use this OR prevHash."
    },
    "format": {
      "type": "string",
      "enum": [
        "text",
        "markdown"
      ],
      "description": "compare cleaned text (default) or structure-preserving markdown"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "true on success; false on an honest failure (still delivered)"
    },
    "url": {
      "type": "string",
      "description": "final URL after redirects"
    },
    "status": {
      "type": "integer",
      "description": "upstream HTTP status of the refetch"
    },
    "changed": {
      "type": "boolean",
      "description": "true if the new content hash differs from the prior reference"
    },
    "fromHash": {
      "type": "string",
      "description": "the prior content hash compared against (0x sha256). null if only prevText with no derivable hash"
    },
    "toHash": {
      "type": "string",
      "description": "the NEW content hash of the refetched text (0x sha256)"
    },
    "comparedBy": {
      "type": "string",
      "enum": [
        "hash",
        "text"
      ],
      "description": "hash = prevHash supplied; text = prevText supplied (full line diff)"
    },
    "diff": {
      "type": "object",
      "description": "deterministic line-level diff (present only when prevText was supplied)",
      "properties": {
        "added": {
          "type": "integer",
          "description": "number of added lines"
        },
        "removed": {
          "type": "integer",
          "description": "number of removed lines"
        },
        "hunks": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "unified-style +/- changed lines (bounded)"
        },
        "truncated": {
          "type": "boolean",
          "description": "true if either side or the hunk list was capped"
        }
      }
    },
    "text": {
      "type": "string",
      "description": "the canonical CHANGE CLAIM string the attestation signs over (the proof, not the page body)"
    },
    "bytes": {
      "type": "integer",
      "description": "raw body size of the refetch"
    },
    "contentType": {
      "type": "string"
    },
    "fetchedAt": {
      "type": "string",
      "description": "ISO timestamp of the refetch (also in the signed receipt)"
    },
    "error": {
      "type": "string",
      "description": "present only when ok:false"
    },
    "attestation": {
      "type": "object",
      "description": "EIP-191 provenance receipt over the canonical change claim (url+changed+fromHash+toHash+time). ecrecoverable OFFLINE (key at /.well-known/mercury-attestation). Proves the change/no-change between hash A and hash B is genuine; chains with the next call's receipt into an audit trail.",
      "properties": {
        "keyId": {
          "type": "string"
        },
        "alg": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "contentHash": {
          "type": "string"
        },
        "nonce": {
          "type": "string"
        },
        "signedAt": {
          "type": "string"
        },
        "signature": {
          "type": "string"
        },
        "verify": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            },
            "howTo": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "required": [
    "ok",
    "url"
  ],
  "additionalProperties": false
}

{
  "ok": true,
  "url": "https://example.com/",
  "status": 200,
  "changed": true,
  "fromHash": null,
  "toHash": "0xc372f751afc12f338f7b3cc8ce610bc548c40338bb80c8e0e0b0c06c707a146c",
  "comparedBy": "hash",
  "text": "mercury-x402:cited-diff:v1\nurl=https://example.com/\nstatus=200\nchanged=1\nfromHash=\ntoHash=0xc372…\nfetchedAt=2026-06-04T00:00:00.000Z",
  "bytes": 513,
  "contentType": "text/html; charset=utf-8",
  "fetchedAt": "2026-06-04T00:00:00.000Z",
  "attestation": {
    "keyId": "mercury-x402-attestation-v1:0x<signer>",
    "alg": "EIP-191-personal_sign",
    "address": "0x<signer-from-/.well-known/mercury-attestation>",
    "contentHash": "0x<sha256 of the change-claim text>",
    "nonce": "0x<16-random-bytes>",
    "signedAt": "2026-06-04T00:00:00.000Z",
    "signature": "0x<65-byte EIP-191 signature>",
    "verify": {
      "message": "mercury-x402:fetch-attestation:v1\nurl=https://example.com/\nstatus=200\nsha256=0x…\nfetchedAt=…\nnonce=0x…",
      "howTo": "EIP-191 ecrecover the message; signer must equal address. Recompute sha256(text)==contentHash; `text` is the signed change claim."
    }
  }
}

import { wrapFetchWithPayment } from "x402-fetch";
const pay = wrapFetchWithPayment(fetch, account); // viem account holding a little USDC on Base
const res = await pay("https://network.mercury-hq.com/buy/diff?url=https://example.com");
const out = await res.json(); // the result + `attestation` (the signed receipt)

# Same route, prepaid API-key rail (Bearer mk_live_…) — get a key at https://network.mercury-hq.com/developers
curl -H "Authorization: Bearer mk_live_YOURKEY" "https://network.mercury-hq.com/buy/diff?url=https://example.com"