Auditor- and integrator-facing reference for the public transparency / Merkle / audit endpoints exposed at https://imdifferent.id. This document is the source of truth; the in-app /transparency/api page renders from it.

Scope: 9 read-only public endpoints (no API key required). Internal scheduled jobs and admin endpoints are out of scope. Voting submission and poll CRUD endpoints are out of scope.

Last updated: 2026-05-18.

Conventions

Endpoint index

GET /api/audit/manifest

Returns a signed manifest that binds the SHA-256 of the verifier script, the verification doc, and the on-chain contract source to the same wallet that anchors Merkle roots on Base. Auditors verify the signature with viem's verifyMessage against signerAddress, then independently SHA the downloaded files (endpoints 2–4) and compare against the sha256 field for each.

Example request

curl -s https://imdifferent.id/api/audit/manifest

Example response — 200 OK

{
  "type": "imdifferent-audit-manifest",
  "version": "v1",
  "files": [
    {
      "name": "verify-merkle.mjs",
      "url": "/api/audit/verifier-script",
      "sha256": "0xe00dab316b8af8a332180566c685faa3c2f5d54b890febe21fcbe6ee8108d453",
      "bytes": 22385
    },
    {
      "name": "MERKLE_VERIFICATION.md",
      "url": "/api/audit/verification-doc",
      "sha256": "0xf7fae72e1bc4618b...",
      "bytes": 54814
    },
    {
      "name": "MerkleAnchor.sol",
      "url": "/api/audit/contract-source",
      "sha256": "0xca863221e996dd67...",
      "bytes": 2407
    }
  ],
  "signedAt": "2026-05-14T03:12:33.193Z",
  "signerAddress": "0x6321cC751D6B41A5D1256019F2AaadCA28dC9321",
  "message": "imdifferent.id audit-manifest v1 | 2026-05-14T03:12:33.193Z | MERKLE_VERIFICATION.md:0xf7fae72e... | MerkleAnchor.sol:0xca863221... | verify-merkle.mjs:0xe00dab31...",
  "signature": "0x1b33d47c9969bde342d8f6e9...",
  "verificationRecipe": "ECDSA-recover(message, signature) === signerAddress (use viem's verifyMessage or ethers' verifyMessage)"
}

Errors

Caching

Cache-Control: public, max-age=300, s-maxage=86400, stale-while-revalidate=86400. Re-signed at every cold-start, so deployed bytes ↔ manifest bytes stay in lockstep.

GET /api/audit/verifier-script

Returns the canonical bytes of scripts/verify-merkle.mjs as a downloadable .mjs file. Pair with endpoint 1 (manifest) to verify the bytes were signed by the anchor wallet.

Example request

curl -s -o verify-merkle.mjs https://imdifferent.id/api/audit/verifier-script
sha256sum verify-merkle.mjs    # compare against manifest.files[name=verify-merkle.mjs].sha256

Response — 200 OK

• Content-Type: text/javascript; charset=utf-8
• Content-Disposition: attachment; filename="verify-merkle.mjs"
• Body: raw script bytes (currently ~22 KB).

Errors

GET /api/audit/verification-doc

Returns the canonical bytes of docs/MERKLE_VERIFICATION.md as a downloadable .md file. Same shape as endpoint 2 with Content-Type: text/markdown.

curl -s -o MERKLE_VERIFICATION.md https://imdifferent.id/api/audit/verification-doc
sha256sum MERKLE_VERIFICATION.md

GET /api/audit/contract-source

Returns the canonical bytes of contracts/MerkleAnchor.sol. Same shape as endpoint 2 with Content-Type: text/plain.

curl -s -o MerkleAnchor.sol https://imdifferent.id/api/audit/contract-source
sha256sum MerkleAnchor.sol

GET /api/merkle/proof/[voteId]

Returns a Merkle inclusion proof for a single ballot. The response always uses the array shape (since Phase 2): cardinality: N and leaves: [...] with N entries.

Path params

Example request

curl -s https://imdifferent.id/api/merkle/proof/20968f36-7f38-44cb-9331-0e04cf2dd37c

Example response — 200 OK (multi-select, cardinality 3)

{
  "voteId": "20968f36-7f38-44cb-9331-0e04cf2dd37c",
  "tier": "mixed",
  "batchDate": "2026-05-13",
  "expectedRoot": "0x5818...8a19",
  "anchor": {
    "txHash": "0xb5e9f5417fb49935bffcc6fa0d1bb516c4f090c6a47cd7da3882c50ad4c737d4",
    "blockNumber": "45968355",
    "chainId": 8453,
    "contractAddress": "0x569e1ca29a8879d1394664ddfa3dad93ea9cc953"
  },
  "cardinality": 3,
  "leaves": [
    {
      "voteId": "20968f36-7f38-44cb-9331-0e04cf2dd37c_<optionId-1>",
      "pollOptionId": "<optionId-1>",
      "position": 14,
      "leafHash": "0xabc...",
      "siblings": [{ "position": "right", "hash": "0xdef..." }, ...]
    },
    { ... }, { ... }
  ]
}

Other response shapes

Caching

Anchored: Cache-Control: public, max-age=300, s-maxage=300, stale-while-revalidate=600. All other states: no-store.

Rate limit

Shared audit-verify budget: 4 req / 60s per IP, shared across endpoints 5, 7, 8, and 9. See docs/RATE_LIMITS.md §25 for the rationale.

GET /api/merkle/poll/[pollId]

Per-poll audit: returns anchored vs claimed tally per option for a sealed poll. Used by the /transparency/poll/[pollId] UI. Designed to expose aggregate integrity (does the on-chain count of leaves per option match the database's claimed voteCount?) without leaking individual ballot IDs.

Path params

Example request

curl -s https://imdifferent.id/api/merkle/poll/c1a55140-81a7-4e81-8ce3-4e56d1b249c8

Example response — 200 OK (sealed poll, status: available)

{
  "status": "available",
  "pollId": "c1a55140-81a7-4e81-8ce3-4e56d1b249c8",
  "sealedAt": "2026-05-13T22:00:00.000Z",
  "batches": [
    {
      "batchId": "...",
      "batchDate": "2026-05-13",
      "tier": "MIXED",
      "leafCount": 6,
      "root": "0x5818...8a19",
      "txHash": "0xb5e9f5417f...",
      "chainId": 8453,
      "contractAddress": "0x569e1ca29a8879d1394664ddfa3dad93ea9cc953",
      "blockNumber": "45968355",
      "anchoredAt": "2026-05-14T02:34:14.000Z",
      "basescanUrl": "https://basescan.org/tx/0xb5e9f5417f..."
    }
  ],
  "totals": {
    "anchoredVotes": 6,
    "claimedTotalVotes": 6,
    "anchoredTallyByOption": [
      { "optionId": "...", "optionText": "Caring",         "count": 2 },
      { "optionId": "...", "optionText": "Social Content", "count": 2 },
      { "optionId": "...", "optionText": "Breeding",       "count": 1 },
      { "optionId": "...", "optionText": "Friendship",     "count": 1 }
    ],
    "claimedTallyByOption": [ /* same shape, mirrors voteCount per option */ ],
    "tallyMatches": true
  }
}

Other status values

Errors

Privacy note

This endpoint deliberately does not return per-ballot IDs or per-voter information. The strongest assertion it can make about an individual ballot is that it was included in some daily Merkle root for the poll's tier — which is what /api/merkle/proof/[voteId] exposes when the voter (or an auditor with the receipt code) supplies the ID directly.

Rate limit

4 handler invocations / 120s per IP, across all polls. Keyed by IP only (not per-poll), so cache-bust loops over distinct poll IDs cap at the IP level rather than starting a fresh window per poll.

Two patterns:

• Same-URL refresh (re-load one audit page): bounded by the CDN cache, not by this rate limit. The 60s s-maxage (see Caching) means the handler runs at most once per 60s per URL — well under the 4-per-120s cap. Refreshing one audit URL in a tight loop is always 200, never 429.
• Cross-URL bursts (open many distinct audit URLs from the same IP in succession): first 4 unique URLs return 200; the 5th onwards returns 429 (also CDN-cached for 60s for the URL it was issued on). At t=120 the per-IP rate-limit window expires and the cycle restarts.

Caching

All responses (200 and 429): public, s-maxage=60 (no stale-while-revalidate).

SWR is deliberately omitted: for cross-URL bursts it would keep a stale 200 served on a URL that should have started returning 429, breaking the rate-limit defence. The audit endpoint is opened once per page-load, never polled, so the synchronous origin call once per 60s is invisible to real users. Net freshness is also better — status transitions (open→sealed, pending→available, new vote arrives) propagate within 60s instead of up to 6–15 min that a per-status SWR window would have allowed.

GET /api/merkle/roots

Anchor Browser data feed. Returns ANCHORED batches and NO_VOTES days (the latter coalesced when filtering all tiers, so a quiet day shows as a single row instead of four).

Query params

Example request

curl -s 'https://imdifferent.id/api/merkle/roots?limit=20&tier=mixed'

Example response — 200 OK

{
  "anchorWalletAddress": "0x6321cC751D6B41A5D1256019F2AaadCA28dC9321",
  "anchorContractAddress": "0x569e1ca29a8879d1394664ddfa3dad93ea9cc953",
  "contractSourceUrl": "https://basescan.org/address/0x569e1ca29a8879d1394664ddfa3dad93ea9cc953#code",
  "chain": "base",
  "chainId": 8453,
  "explorerBaseUrl": "https://basescan.org/tx/",
  "easAttestation": "0x...",
  "easAttestationUrl": "https://base.easscan.org/attestation/view/0x...",
  "roots": [
    {
      "batchDate": "2026-05-13",
      "tier": "mixed",
      "leafCount": 41,
      "root": "0x5818...8a19",
      "anchoredAt": "2026-05-14T02:34:14.000Z",
      "txHash": "0xb5e9f5417f...",
      "blockNumber": "45968355",
      "signingKeyVersion": 1,
      "hmac": "0x...",
      "status": "ANCHORED"
    },
    {
      "batchDate": "2026-05-12",
      "tier": "all",
      "leafCount": 0,
      "root": "",
      "anchoredAt": "2026-05-13T03:30:00.000Z",
      "txHash": "",
      "blockNumber": "0",
      "signingKeyVersion": 0,
      "hmac": "",
      "status": "NO_VOTES",
      "isCoalesced": true
    }
  ],
  "generatedAt": "2026-05-14T03:13:00.000Z"
}

Errors

Caching

revalidate = 300 (5 min). Anchors update at most once per day, so a 5-minute stale window is generous.

Pending fields

The response carries _anchorBasename_pending, _contractDeployedAt_pending, _lastProofOfLife_pending, and (when applicable) _easAttestation_pending. These are placeholders for fields that will be populated in later phases (Basename registration, monthly proof-of-life publication, etc.). Treat them as informational; don't rely on the underscore-prefixed keys staying around once the real fields land.

Rate limit

Shared audit-verify budget — see endpoint 5's rate limit note.

POST /api/merkle/verify (also GET ?code=…)

End-to-end receipt verification: validates the receipt hash, looks up the matching ballot, AND confirms the Merkle inclusion proof passes against the on-chain root. Used by the /transparency/verify UI. The single-call equivalent of (endpoint 9 + endpoint 5).

POST body

GET query

Example request — POST

curl -s -X POST https://imdifferent.id/api/merkle/verify \
  -H 'Content-Type: application/json' \
  -d '{"voteId":"20968f36-7f38-44cb-9331-0e04cf2dd37c","hash":"abc..."}'

Example request — GET

curl -s 'https://imdifferent.id/api/merkle/verify?code=20968f36-7f38-44cb-9331-0e04cf2dd37c:abc...:ledgerXYZ'

Example response — 200 OK (anchored, multi-select)

{
  "success": true,
  "receiptValid": true,
  "merkle": {
    "anchored": true,
    "tier": "mixed",
    "batchDate": "2026-05-13",
    "txHash": "0xb5e9f5417f...",
    "txUrl": "https://basescan.org/tx/0xb5e9f5417f...",
    "blockNumber": "45968355",
    "verifiedAt": "2026-05-14T06:30:00.000Z",
    "cardinality": 3,
    "selections": [
      { "pollOptionId": "<optionId-1>", "leafHash": "0xabc...", "anchored": true },
      { "pollOptionId": "<optionId-2>", "leafHash": "0xdef...", "anchored": true },
      { "pollOptionId": "<optionId-3>", "leafHash": "0xfff...", "anchored": true }
    ]
  }
}

Other response shapes

Errors

Rate limit

Shared audit-verify budget — see endpoint 5's rate limit note.

POST /api/receipts/verify

Receipt-only verification: validates the receipt hash without performing the Merkle inclusion check. Used by the /[lang]/receipts page to give voters an immediate "your receipt is real" answer before the slower Merkle round-trip. Prefer endpoint 8 if you want the full audit chain in one call.

POST body

Example request

curl -s -X POST https://imdifferent.id/api/receipts/verify \
  -H 'Content-Type: application/json' \
  -d '{"voteId":"20968f36-7f38-44cb-9331-0e04cf2dd37c","hash":"abc..."}'

Example response — 200 OK (success)

{
  "success": true,
  "data": {
    "voteId": "20968f36-7f38-44cb-9331-0e04cf2dd37c",
    "pollTitle": "Why do people bond with cats?",
    "pollLanguage": "en",
    "pollTranslations": [ /* localized titles */ ],
    "hashAlgorithm": "SHA-256 Verified"
  }
}

Other response shapes

Errors

Rate limit

Shared audit-verify budget — see endpoint 5's rate limit note.

Receipt hash recipe

The hash component of a receipt code is computed by the server when the vote is recorded, then handed back to the voter as the second segment of voteId:hash[:ledgerEntryId].

hash = SHA-256(`${internalId}-${pollId}-${voterIpHash}-${ledgerEntryId || 'null'}`)

Backward-compatible legacy recipe (pre-§B.3 receipts):

hash = SHA-256(`${internalId}-${pollId}-${voterIpHash}`)

The verify endpoints accept either recipe — the server tries both and matches whichever passes. Note: pollOptionId is intentionally NOT part of the hash. One ballot, one receipt, even when N selections sit underneath.

Dual-era lookup

Any endpoint that takes a voteId accepts BOTH:

1. A ballot_id (UUID) — every ballot cast since the Phase 1 cutover at 2026-05-13 21:15 UTC has one. This is the canonical receipt identifier going forward (single-select and multi-select alike).
2. A legacy vote_id (UUID) — every vote cast before Phase 1 has one, and was never associated with a Phase 1 ballot.

Resolution behaviour (used by endpoints 5, 8, 9):

1. The backend first tries the value as a Phase 1+ ballot identifier. If found → it is used directly as internalId.
2. Otherwise the backend tries it as a legacy vote identifier — including via prefix match, since legacy vote identifiers may carry a trailing _<optionId> suffix that must be stripped before comparison.
3. If neither path matches → 404 not_found.

Why the prefix fallback exists: the legacy identifier was constructed as ${ballotId}_${optionId} for single-select Phase 1 too, so a Phase 1 ballot ID is also the prefix of the corresponding legacy vote ID. The prefix match catches the case where someone hands you the wrong half (the full vote ID instead of the parent ballot ID).

Tier classification (for context)

The daily Merkle anchoring process classifies each vote into exactly one tier based on the verification methods present on its ballot:

Each tier produces a separate daily Merkle batch; each batch produces one root, one transaction, one EAS attestation. The Anchor Browser (endpoint 7) returns one row per (date, tier) pair, except where coalescing applies.

Worked examples

A. Verify your own multi-select ballot end-to-end

RECEIPT="20968f36-7f38-44cb-9331-0e04cf2dd37c:abc123def456..."

curl -s "https://imdifferent.id/api/merkle/verify?code=${RECEIPT}" | jq

You should see success: true, receiptValid: true, merkle.anchored: true, merkle.cardinality: 3, and three entries in merkle.selections[].

B. Re-verify the same ballot with the standalone script

# Download the verifier and the manifest in parallel
curl -s -o verify.mjs https://imdifferent.id/api/audit/verifier-script
curl -s    https://imdifferent.id/api/audit/manifest > manifest.json

# Confirm the bytes match what the manifest says
echo "$(sha256sum verify.mjs | cut -d' ' -f1)" \
  | grep -i "$(jq -r '.files[] | select(.name=="verify-merkle.mjs") | .sha256[2:]' manifest.json)" \
  && echo OK

# Run the verifier (uses /api/merkle/proof/[voteId] under the hood)
node verify.mjs --vote-id=20968f36-7f38-44cb-9331-0e04cf2dd37c \
                --base-url=https://imdifferent.id

C. Audit a sealed poll's tally

curl -s https://imdifferent.id/api/merkle/poll/c1a55140-81a7-4e81-8ce3-4e56d1b249c8 | jq '.totals'

Look for tallyMatches: true. If false, every option's claimedCount vs anchoredCount is shown so you can identify which option drifted.

D. Pull the last 7 days of anchors

curl -s 'https://imdifferent.id/api/merkle/roots?limit=200' | jq '.roots | map(select(.batchDate >= "2026-05-08"))'

Voter count vs. selection count

Added 2026-05-17.

Endpoint 6 (/api/merkle/poll/[pollId]) distinguishes two numbers that historical responses called "votes" interchangeably:

The /api/merkle/poll/[pollId] totals block now returns BOTH naming conventions:

Integrators reading claimedTotalVotes / anchoredVotes continue to work unchanged. New integrators should read the canonical names.

For sealed-poll JSON snapshots (returned alongside poll metadata), snapshots written on or after 2026-05-17 carry an explicit selectionCount field. Older snapshots omit it and the read path computes it on the fly from options[].voteCount. Both shapes resolve to the same number — the new field is a forward migration so we can drop the recompute once legacy seals age out.

Change log