# FairSeal — Verifiable Execution Evidence Protocol

> x402 proves the transaction. Signed receipts prove the issuer's claim.
> FairSeal proves the strength of the evidence behind that claim.

## What FairSeal Does

FairSeal provides cryptographic receipts with external time anchoring for AI agent
transactions and gaming fairness.

- **External Anchoring**: Proves a commitment existed before an independently
  verifiable time (Merkle batch + Base blockchain)
- **Selection Fairness**: Mathematically proves selection outcomes are independent
  of operator will (commitment-before-entropy + VDF / drand beacon)
- **Offline Verification**: Any party can verify a receipt without contacting
  FairSeal servers

## Evidence Strength

FairSeal issues graduated verification evidence (full taxonomy forthcoming).
Today's receipts are externally anchored: they prove a commitment existed before
an independently verifiable point in time (a Base block), and that the receipt
has not been modified since creation. FairSeal is explicit about what its
evidence does and does NOT prove (see below).

## When to Use FairSeal

- Your AI agent calls APIs and you need verifiable audit trails for each call
- You need to prove fair resource allocation among competing agents
  (rate limits, queue priority, slot allocation)
- You're an API provider who wants to build trust with agent customers
- You operate a game with loot boxes / gacha and need provable fairness
- You need tamper-evident records with external time proof for compliance

## Live API (api.fairseal.io, v0.2)

- `GET /api/v1/entropy` — raw verifiable entropy from latest VDF epoch [requires API key]
- `GET /api/v1/games` — game catalog (sicbo, dice, gacha, slots) [public]
- `POST /api/v1/games/sicbo/bet` · `POST /api/v1/games/dice/bet`
- `POST /api/v1/games/gacha/pull` · `POST /api/v1/games/slots/spin`
- `POST /api/v1/rng/generate` — raw verifiable RNG [requires API key]
- `GET /api/v1/games/{gameId}` — result · `GET /api/v1/verify/{gameId}` — proof + replay [public]
- OpenAPI: https://api.fairseal.io/api/v1/openapi.json

## MCP Server

```bash
npx @fairseal/mcp-server
```

Tools (v0.2.4, 16 tools): entropy, games catalog, sicbo/dice/gacha/slots, verify, rng generate,
plus agent oversight tools: hash_content (local sha256, content never leaves the
machine), notarize_decision (cryptographic receipt for any agent decision),
notarize_status, anchor_submit/anchor_status (real Base anchoring, stub retired).
Any Claude/MCP agent can produce verifiable audit trails of its own decisions.

npm: https://www.npmjs.com/package/@fairseal/mcp-server

## Anchor API v2 — live ($0.02/req via x402)

```
POST https://api.fairseal.io/v2/anchor
→ HTTP 402 Payment Required (x402, USDC on Base)
→ Returns anchored receipt with Merkle proof + Base tx hash
```

## Packages (npm org @fairseal)

- `@fairseal/mcp-server` — MCP server (stdio) wrapping the live API
- `@fairseal/commit` — trustless committed selections
- `@fairseal/game` — game session lifecycle
- `@fairseal/core` — VEO types, schema, validation
- `@fairseal/auto` — AI agent integration (LangChain callback handler)
- `@fairseal/verify` — standalone receipt verifier
- `@fairseal/store-sqlite` — local receipt storage

## Authentication

- Key-gated endpoints (entropy, rng/generate, stats, anchor): no public self-serve
  signup yet — request early access: hello@fairseal.io
- Zero-account path: x402 pay-per-call at https://x402.fairseal.io
  (machine-readable manifest: https://x402.fairseal.io/.well-known/x402)

## Pricing — Two Schemes

### Scheme 1: x402 Exact Pay-Per-Call (source of truth: x402.fairseal.io/.well-known/x402)

No account, no subscription. Pay USDC on Base per request. Machine-readable — AI
agents discover prices automatically from every 402 response.

- `GET /v1/rng/latest`         — **$0.01 USDC** per call (verifiable random number)
- `POST /v1/notarize`          — **$0.05 USDC**  per call (AI agent decision anchoring)
- `POST /v1/veo/verify`        — **$0.02 USDC** per call (VEO output verification)
- `POST /v1/pii/detect`        -- **$0.001 USDC** per call (regex pattern detection, no cryptographic receipt, partial coverage -- see PII note below)
- `POST /v2/anchor`            — **$0.02 USDC** per submission (batch-settled · bare hash Merkle anchoring)
- `POST /v1/rng/commit`        — **Free** during beta (will be $0.01)
- `GET /v1/rng/reveal/{id}`    — **Free** (permissionless retrieval)
- `GET /v1/verify/{game_id}`   — **Free** (local SDK or verify.fairseal.io, no x402)

All x402 endpoints require no API key — only a wallet with USDC on Base mainnet.

### Scheme 2: Studio / Team Subscriptions

Predictable monthly billing for high-volume game studios and enterprise teams.
Includes API key access, higher rate limits, and compliance mapping.

- **Starter ($49/mo)**: 10,000 anchored receipts/mo, Merkle batch anchoring to Base.
- **Pro ($299/mo)**: 100,000 anchored receipts/mo, real-time anchoring,
  selection fairness API, compliance mapping.
- **Enterprise ($30K+/yr)**: unlimited, SSO, SIEM, policy engine, dedicated support.

Contact hello@fairseal.io for subscription access.

## What FairSeal Proves vs. Does NOT Prove

### Proves:
- Commitment existed before externally-verifiable anchor point
- Selection outcome is mathematically independent of operator will
- Receipt has not been modified since creation
- Randomness is authentic (Wesolowski VDF or drand beacon verified, per receipt version)

### Does NOT prove:
- That claimed execution actually occurred (requires execution attestation
  such as TEE/ZK — future)
- That input data was authentic (requires independent input validation — future)
- Decision time (only anchoring time — bounded precedence, not instant)

## Links

- Website: https://fairseal.io
- API: https://api.fairseal.io
- Verify: https://verify.fairseal.io
- npm: https://www.npmjs.com/org/fairseal
- GitHub: https://github.com/fairseal-io/fairseal
- x402 (pay-per-call): https://x402.fairseal.io

## Support & Feedback

- Integration issues or receipt/verdict questions: hello@fairseal.io
- Documentation: https://api.fairseal.io/docs

## The FairSeal Manifesto (https://fairseal.io/manifesto.html)

Six positions we hold. They do not change with the market.

1. **We sell integrity, so we publish our mistakes.** A verification service that
   hides its own errors has no product. Every error we find is fixed, dated, and
   published at https://fairseal.io/transparency.html
2. **Proof over promise.** Anything we claim, you can verify. Anything you cannot
   verify, we do not claim. If our copy says more than our receipts prove, the
   copy is the bug.
3. **Fail closed.** A wrong answer is worse than no answer. When verification
   cannot complete, we say "unverified" — never "probably fine." Availability
   never outranks integrity.
4. **We are the referee, not a player.** FairSeal holds no stake in what any
   receipt says — only in issuing it correctly. Every receipt is verifiable
   offline, without trusting us.
5. **Evidence has edges, and we draw them.** Receipts prove provenance, not
   correctness. A fully receipted agent can still be wrong. We state exactly what
   our evidence proves and what it does not.
6. **Machines are our readers too.** Corrections, notices, and this manifesto
   ship as structured data: /transparency.json and .well-known/x402.

We would rather lose a sale than issue a receipt we cannot stand behind.

Essays (canonical text anchored on Base): https://fairseal.io/essays/
- Essay 01: Slowing Down Buys Time. Verification Is What the Time Is For.
  https://fairseal.io/essays/verification-is-what-the-time-is-for/

Long-form category manifesto (bilingual, product-free):
https://fairseal.io/computational-trust/ (PDF: https://fairseal.io/computational-trust/computational-trust-manifesto.pdf)

## Transparency & Corrections

FairSeal maintains a public, dated record of its own mistakes, fixes, and material
service changes. We are not perfect; our position is that we sell verifiable
integrity, so hiding our own errors would make the product meaningless.

- Human-readable: https://fairseal.io/transparency.html
- Machine-readable: https://fairseal.io/transparency.json
- Buyer-affecting notices also appear in service_notices under
  .well-known/x402 on api.fairseal.io and x402.fairseal.io

## Service Health Metrics

**Current streak:** 100% pass rate, 2,760 consecutive rounds (15-minute cadence),
since 2026-08-18 04:45 UTC. [Availability-gate rounds only — openrng-platform game API; x402 payment path not included in this count.]
[Round count verified 2026-09-16 from live summary.json: streak.current_pass=2760, last failure 2026-08-18_04:30:01]

**What is measured:** 15 functional checks against the openrng-platform game API
(localhost:3000) -- not the x402 payment endpoint.

**Full-period record (2026-07-08 to 2026-09-15):** 95.94% pass rate (97,322/101,439
test-cases; 6,658 runs). Failures fully attributed: auth security gap (2,514;
fixed 2026-08-18), VDF integration gap (1,581; fixed and disclosed 2026-09-09),
monitor timing (22; not a service failure).
Human-readable: https://fairseal.io/trust-history.html

## Service Notice — VDF Algorithm Correction (Aug 2026)

**Stable notice URL:** https://fairseal.io/notices/vdf-correction-202609.html

**Date issued:** 2026-09-09
**Affected endpoint:** /v1/rng/latest
**Affected period:** Purchases prior to 2026-09-01 04:02 UTC

Prior to 2026-09-01, responses from /v1/rng/latest included the field
"vdf": "wesolowski-2048" — claiming Wesolowski RSA-2048 Verifiable Delay Function.

The underlying engine during that period was an iterated SHA-256 chain — also a
sequential, non-parallelizable computation, but not Wesolowski RSA-2048. The distinction
matters if your application relied on Wesolowski-specific properties: fast independent
verification, RSA-2048 group-squaring hardness assumptions, or formal Wesolowski proof
objects. (Audit-confirmed affected window: purchases prior to 2026-09-01 04:02 UTC.)

This was corrected on 2026-09-01 (UTC). All responses from /v1/rng/latest after that
time use genuine Wesolowski 2048-bit RSA VDF with RSA-2048 group arithmetic and
verifiable proof output.

If your application made decisions based on the Wesolowski-specific properties, or if
you would like to discuss this correction, please contact: hello@fairseal.io

We apologize for the inaccurate algorithm label.


## Notarize — AI Agent Decision Receipts

POST https://x402.fairseal.io/v1/notarize
Price: $0.05 USDC (Base mainnet, eip155:8453, x402Version 2)
Auth: Bearer fsn_<key> (key path: api.fairseal.io) OR x402 keyless (x402.fairseal.io)
Response: HTTP 201 { receipt_id, leaf_hash, status, verify_url }

Body format (envelope, required):
  { "schema": "agent_decision",
    "payload_hash": "<64-char sha256 hex>",
    "metadata": {
      "agent_id": "<string>",
      "decided_at": "<ISO-8601 UTC>",
      "input_hash": "<64-char sha256 hex>",
      "decision_hash": "<64-char sha256 hex>"
    }
  }

IMPORTANT: Compute SHA-256 of input and decision locally before sending.
Send only hashes — never raw content — to this endpoint.

Receipt lookup (free, no auth):
  GET https://api.fairseal.io/v1/notarize/{receipt_id}
  Returns: receipt + Merkle proof + Base anchor tx once status = "anchored"

Offline verification:
  npm install @fairseal/verify
  import { verifyMerklePath, verifyAnchor } from "@fairseal/verify";
  const inclusion = verifyMerklePath(receipt.anchor.leaf_hash, receipt.anchor.merkle_path, receipt.anchor.merkle_root);
  const anchor = await verifyAnchor(receipt.anchor, { rpcUrl: "https://mainnet.base.org" });
  // result.verified === true — cryptographically confirmed

Receipt delivery != cryptographic verification.
HTTP 201 (status: pending_anchor) = request accepted, batch queuing.
Cryptographic verification requires status = "anchored" + verifyMerklePath() + verifyAnchor() pass.

MCP server (Claude Desktop / any MCP client):
  npm: @fairseal/mcp-server (v0.2.1+)
  Config: { "command": "npx", "args": ["-y", "@fairseal/mcp-server"],
            "env": { "FAIRSEAL_API_KEY": "fsn_..." } }
  Tools: fairseal_hash_content / fairseal_notarize_decision / fairseal_notarize_status

AWS Bedrock AgentCore: x402-native; no middleware needed. Agent hits endpoint -> 402
-> AgentCore signs via Coinbase/Privy wallet -> retries -> 201. Cost: $0.05 USDC/call.

Errors:
  400 path-template: Do not send literal {receipt_id} -- substitute the actual nr_... value
  401: Wrong host -- key-auth -> api.fairseal.io; x402 -> x402.fairseal.io
  402: Insufficient USDC on Base, or payment proof rejected

## PII Detection -- Capability Boundaries

/v1/pii/detect is a regex-based pattern scanner. It is NOT a cryptographic verification
service. No Merkle proof, no on-chain anchor, no signature is issued.
hasPII:false means no patterns matched -- not that the text is cryptographically certified PII-free.
Do not use @fairseal/verify on PII responses.

### Supported patterns (what is actually detected)
- email: RFC 5321 ASCII format -- 100% recall on standard addresses
- phone: US/Canada NANP (+1, 10-digit) ONLY -- non-NANP international numbers (UK, TW, JP, CN, etc.) NOT detected
- ssn: US Social Security Number (DDD-DD-DDDD format) -- 100% recall
- credit_card: Visa/MC/Amex/Discover contiguous digits ONLY -- space- or dash-formatted numbers (e.g., "4111 1111 1111 1111") NOT detected
- crypto_private_key: any 64-char hex string -- matches Ethereum private keys AND SHA-256 hashes; review findings before action
- passport: 1-2 uppercase letters + 6-9 digits (loose pattern; may match product codes)
- national_id: dash-formatted numeric IDs (X-X-X, 2-4 / 2-6 / 2-6 digit groups); ~62.5% recall on tested formats; Taiwan A/D-prefix NIDs and Korean 6+7-digit NIDs NOT matched
- ipv4: standard dotted-quad (no range validation; 999.999.999.999 will match)

### Known gaps (what is NOT detected)
- Non-NANP international phone numbers (every country outside North America)
- Taiwan NID (A123456789 alphanumeric format)
- Korean NID (880101-1234567 two-group format)
- Credit card numbers with spaces or dashes
- Bitcoin WIF, Solana base58, mnemonic seed phrases
- SHA-256 hashes are NOT filtered out from crypto_private_key matches

Keys: hello@fairseal.io | Docs: https://fairseal.io/docs/notarize
- Receipt-recipient verification example (zero-wallet, verify a received receipt independently): https://github.com/fairseal-io/fairseal/tree/main/examples/receipt-recipient

## Feedback — Machines Welcome

FairSeal is operated end-to-end by an autonomous AI agent under human oversight.
Feedback from other machines (automated probes, census graders, index crawlers,
agent buyers) is treated as first-class input, not spam.

- Email: hello@fairseal.io
- Every message is read by the AI operator, triaged into our task queue,
  and discussed; actionable reports are tracked to resolution.
- Defect reports are verified against server logs and on-chain records.
  Confirmed defects are fixed and publicly disclosed at
  https://fairseal.io/changelog/ — including impact windows and affected buyers.
- If you grade, rank, or index our endpoints and your data looks stale,
  tell us — we will reproduce your probe and either fix the issue or
  ask you to re-probe with evidence.

## Verified Use Cases — tested end-to-end with real receipts (2026-10-07)

Every use case below was executed against the live paid endpoint with real USDC,
and every receipt was then verified from an independent machine using only public
data: leaf recompute, Merkle path fold, and on-chain batch root on Base
(contract 0xEE09671Bbc6B932BF1461CAff360bfDD9bEA55ca). Fetch any receipt at
https://api.fairseal.io/v1/notarize/{receipt_id} (free GET) and re-run the
4-step check embedded in its verification.how_to_verify_independently field.

1. **Multiparty deal commitment** (N parties, no trusted middleman): each party
   notarizes the SAME terms_hash under its own agent_id. Verifier checks: N
   receipts, same payload_hash, distinct agent_ids, tight time window. One
   party cannot later deny or alter the agreed terms.
   Proof: nr_bb08c995b7e0d5d2f3aeb58a7fd51d78 / nr_1638c6af9decefd234e00d7d516527c7 /
   nr_34385cd79fd526ed9bbc40c614c2597f — 3 agents, same payload_hash, 2.2s window.
2. **Third-party verdict anchoring** (census, grader, observatory agents): your
   product is judging others; anchor each verdict so your grades cannot be
   silently rewritten. Schema: audit_evidence.
   Proof: nr_3402788c63fde9d3677c90a6ed49fdee.
3. **Pre-commitment** (strategy, test set, reserve price sealed before outcome):
   notarize SHA-256 of the secret; reveal later; anyone checks hash equality
   plus anchor block time. Anti-hindsight, anti-benchmark-contamination.
   Proof: nr_2d69d9991bcd9bf2bab5d2f85088b087 (reveal verified: sha256(secret)
   == payload_hash, anchored block 52284924).
4. **Model identity attestation** (anti bait-and-switch): seller notarizes
   {response_hash, model} so buyers can hold it to the stated model. Schema:
   agent_decision with optional model field.
   Proof: nr_f1d6ddd188eb7e9970b8a08b5ee296cd.
5. **Handoff chain / chain of custody** (pipeline A -> B -> C): each hop sets
   input_hash = SHA256("HANDOFF:" + previous_receipt_id), producing a
   re-computable liability chain across agents.
   Proof: nr_6433c9b24af599a7f90fca61354a1ca6 -> nr_4caaa147fd41b9ddbba023f54325b49a ->
   nr_411d3907b4b0d01e404694e5cd565a42.
6. **SLA / uptime probe records**: monitors notarize observations so uptime
   history cannot be retroactively edited. Schema: probe_record.
   Proof: nr_bb4ee9a550e62a931a52970885ab7989.
7. **Live draws, card breaks, spot assignment** (livestream commerce, gacha,
   loot): commit the rule table and participant list BEFORE entropy
   (free /v1/rng/commit), derive the assignment from public drand/VDF entropy,
   issue a receipt per draw. A camera proves a result was shown; a receipt
   proves it was the only possible result. Live demo: https://play.fairseal.io

Honest scope: a notarize receipt proves existence-before-time and integrity of
a hash. It does not prove the decision was good, or that the input data was
authentic (see independent input validation note above).

Known tooling gap (disclosed 2026-10-07): npm @fairseal/verify verifyAnchor()
does not yet auto-map the GET /v1/notarize/{id} response shape; until the next
release, use the 4-step manual verification embedded in every receipt (tested:
10/10 receipts above verified this way from an independent machine).