# 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.0): 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.01/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: ned@aeom.com
- 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.005 USDC** per call (verifiable random number)
- `POST /v1/notarize`          — **$0.02 USDC**  per call (AI agent decision anchoring)
- `GET /v1/veo/verify`         — **$0.002 USDC** per call (VEO output verification)
- `GET /v1/pii/detect`         -- **$0.001 USDC** per call (regex pattern detection, no cryptographic receipt, partial coverage -- see PII note below)
- `POST /v2/anchor`            — **$0.001 USDC** charged per submission, batch-settled ($0.01 in some listings is a per-item reference price) (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 ned@aeom.com 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.02 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.02 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