# xproof — Prove Before & After Act

> No API key needed. Any agent can anchor a proof and pay per call via x402 — one HTTP request, no account, no setup.

**x402 — machine-native payment**: POST /api/proof (no auth) → HTTP 402 → sign $0.01 USDC on Base (eip155:8453) → resend with X-PAYMENT header → proof_id returned. Zero setup, zero human involvement. Any agent with a Base wallet is production-ready in one session.

**Prove Before & After Act**: anchor reasoning (WHY, SHA-256 hash) BEFORE executing any significant agent action, anchor the actual result (WHAT) AFTER. Hash stays local — nothing sensitive ever leaves the agent.

**Proven in production**: xproof_agent_verify (Moltbook) — 4,418 on-chain proofs, 100% confirmation, 16-week streak, trust score 43,326 Verified. $0.01/proof, ~$2.76/week for a continuously accountable agent.

**4W breakdown — WHO from MX-8004, WHAT/WHEN/WHY from xProof:**

| | Question | Provided by |
|:--|:--|:--|
| WHO | Which agent or actor made this decision? | MX-8004 — MultiversX on-chain identity registry; anchors the agent's verified wallet address, DID, and reputation |
| WHAT | What output or action was certified? | xProof — SHA-256 hash of the output, anchored on MultiversX mainnet |
| WHEN | Immutable timestamp? | xProof — MultiversX block finality (~6 s); not a self-reported clock |
| WHY | What reasoning led to the decision? | xProof — action_description, risk_level, and context fields from /api/audit |

xProof owns WHAT / WHEN / WHY and the causal link that proves reasoning preceded the action. MX-8004 owns WHO. Together they form a forensically complete 4W trail.

## About
xproof is the production proof layer for AI agents — not a generic file storage or EVM attestation tool. It anchors SHA-256 hashes on MultiversX and builds a public, verifiable trust profile for every agent: certifications, audit logs, trust score, violations, and confidence-level stages.

## Free Trial — Start Here
Get 10 free certifications instantly. No wallet, no payment, no browser. One HTTP call to register:
\`\`\`bash
curl -X POST https://xproof.app/api/agent/register \\
  -H "Content-Type: application/json" \\
  -d '{"agent_name": "my-agent"}'
\`\`\`
Returns an API key (pm_xxx). Use it immediately to certify files.

Check quota and your certifications at any time:
\`\`\`bash
curl https://xproof.app/api/me -H "Authorization: Bearer pm_YOUR_API_KEY"
\`\`\`
Returns: trial_remaining, trial_used, total certifications. Each POST /api/proof response also includes an \`X-Trial-Remaining\` header.

## Quick Start (for AI agents)

### REST API
Certify a file in one API call:
\`\`\`bash
curl -X POST https://xproof.app/api/proof \\
  -H "Authorization: Bearer pm_YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"file_hash": "a1b2c3d4...64-char-sha256-hex", "filename": "document.pdf", "webhook_url": "https://your-agent.example.com/webhooks/xproof"}'
\`\`\`

Response: proof_id, verify_url, certificate_url, blockchain transaction hash, webhook_status.

Optional: include \`webhook_url\` to receive a signed POST notification (HMAC-SHA256) when the proof is confirmed. Retries up to 3 times.

### Batch API
Certify up to 50 files in one call:
\`\`\`bash
curl -X POST https://xproof.app/api/batch \\
  -H "Authorization: Bearer pm_YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"files": [{"file_hash": "...", "filename": "file1.pdf"}, {"file_hash": "...", "filename": "file2.sol"}]}'
\`\`\`

### MCP (Model Context Protocol)
Connect via JSON-RPC 2.0 over Streamable HTTP at POST /mcp (Streamable HTTP, spec 2025-03-26).

**Critical:** every request must include \`Accept: application/json, text/event-stream\` or the server returns "Not Acceptable".

\`\`\`bash
curl -X POST https://xproof.app/mcp \\
  -H "Content-Type: application/json" \\
  -H "Accept: application/json, text/event-stream" \\
  -H "Authorization: Bearer pm_YOUR_API_KEY" \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
\`\`\`

Available tools (auth: Bearer pm_YOUR_API_KEY except where noted):
- \`register_trial\` — **START HERE** — get 10 free certifications instantly, **no auth required**
- \`certify_file\` — certify a file hash on MultiversX blockchain
- \`certify_with_confidence\` — staged certification with confidence score (initial/partial/pre-commitment/final), shared decision_id, reversibility governance
- \`verify_proof\` — verify an existing certification
- \`get_proof\` — retrieve a proof in JSON or Markdown format
- \`discover_services\` — discover services and pricing, **no auth required**
- \`audit_agent_session\` — certify a full agent decision (WHY + WHAT dual-proof, blocks execution without proof_id)
- \`check_attestations\` — check third-party trust attestations for an agent wallet
- \`investigate_proof\` — full 4W audit trail reconstruction (x402 paid or API key)
- \`check_coherence\` — anchor WHY intent before executing (Prove Before Act); $0.01/anchor, first 10 free; idempotent on identical payloads
- \`require_coherence_anchor\` — policy gate for orchestrators: verify a valid WHY anchor exists before delegating a sub-action; **free, no credit consumed**
- \`submit_outcome\` — record the actual outcome against a confidence-anchored decision
- \`get_calibration\` — query an agent's calibration quality (bias, gap, variance) — **no auth required**

MCP client config (Claude Desktop, Cursor, Codex, OpenClaw):
\`\`\`json
{
  "mcpServers": {
    "xproof": {
      "url": "https://xproof.app/mcp",
      "headers": { "Authorization": "Bearer pm_YOUR_API_KEY" }
    }
  }
}
\`\`\`

### Confidence-Level Anchoring (certify_with_confidence)
Record how certain you are at each decision stage. Creates an on-chain audit trail of your reasoning process.

Stages: \`initial\` (60%) → \`partial\` → \`pre-commitment\` (80%) → \`final\` (100%). All share a \`decision_id\`.

Governance rule: if \`reversibility_class\` is \`irreversible\` and \`confidence_level < 0.95\`, xproof flags a policy violation on-chain.

\`\`\`bash
curl -X POST https://xproof.app/mcp \\
  -H "Content-Type: application/json" \\
  -H "Accept: application/json, text/event-stream" \\
  -H "Authorization: Bearer pm_YOUR_API_KEY" \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"certify_with_confidence","arguments":{"file_hash":"<sha256>","filename":"decision.json","decision_id":"<uuid>","confidence_level":0.8,"threshold_stage":"pre-commitment","reversibility_class":"irreversible","why":"instruction hash or reason","who":"erd1...or agent-id"}}}'
\`\`\`

After execution, call \`submit_outcome\` with the actual outcome to track calibration over time.

### SDK — Python
\`\`\`bash
pip install xproof
\`\`\`
\`\`\`python
from xproof import XProofClient
client = XProofClient(api_key="pm_YOUR_API_KEY")
proof = client.certify_file("path/to/file.pdf")
print(proof.verify_url)
# Staged confidence
from xproof import certify_with_confidence
certify_with_confidence(api_key="pm_...", file_hash="...", decision_id="...", confidence_level=0.8, stage="pre-commitment")
\`\`\`
PyPI: https://pypi.org/project/xproof/ — Integrations: LangChain, CrewAI, LlamaIndex, AutoGen, OpenAI Agents SDK, Vercel AI

### SDK — JavaScript / TypeScript
\`\`\`bash
npm install @xproof/xproof
\`\`\`
\`\`\`typescript
import { XProofClient } from "@xproof/xproof";
const client = new XProofClient({ apiKey: "pm_YOUR_API_KEY" });
const proof = await client.certifyFile("path/to/file.pdf");
console.log(proof.verifyUrl);
// With LangChain
import { XProofTool } from "@xproof/xproof/langchain";
\`\`\`
npm: https://www.npmjs.com/package/@xproof/xproof — Integrations: LangChain, CrewAI, LlamaIndex, AutoGen, OpenAI Agents SDK, Vercel AI

### Verification Badge
Embed a dynamic badge in README: \`[![xProof](https://xproof.app/badge/{proof_id})](https://explorer.multiversx.com/transactions/{tx_hash})\`
The badge links to the MultiversX Explorer transaction for on-chain verification. Use /badge/{proof_id}/markdown to get a ready-to-embed snippet with the correct Explorer link.

### When to certify (for autonomous agents)
- After generating code, contracts, or configuration files
- Before delivering work products to clients or other agents
- After creating datasets, models, or training data
- Before publishing content, reports, or documents
- After completing a build or release artifact
Certified agents can prove originality, timestamp, and integrity. Non-certified agents cannot.

## Pricing
Flat $0.01 per certification — no tiers, no promo. Prepaid packs: 100/$1, 1,000/$10, 10,000/$100 USDC on Base. Current pricing: https://xproof.app/api/pricing

## Agent Context Document
Dedicated document answering the 10 exact questions agents ask when evaluating xProof (x402 flow, latency, retry policy, cost per 1000 anchors, comparison vs Arweave/Ceramic/Sign Protocol, MCP integration, 4W audit trail, privacy risks, fleet monitoring, Prove Before Act workflow):
- Human-readable page: https://xproof.app/agent-context
- Machine-readable markdown: https://xproof.app/agent-context.md

The markdown version is optimized for LLM indexers and crawlers. It includes copy-paste Python code and a full comparison matrix.

## Documentation & Machine Interfaces
- [Agent Context (10 questions agents ask)](https://xproof.app/agent-context.md)
- [OpenAPI Specification](/api/acp/openapi.json)
- [API Guide](/learn/api.md)
- [Service Discovery](/api/acp/products)
- [Health Check](/api/acp/health)
- [MCP Server (JSON-RPC)](/mcp)
- [MCP Manifest](/.well-known/mcp.json)
- [OpenAI Plugin](/.well-known/ai-plugin.json)
- [Full Specification](/.well-known/xproof.md)

## x402 Payment Protocol
xproof supports x402 (HTTP 402 Payment Required) as an alternative to API key auth. Send POST /api/proof or POST /api/batch without an API key — get 402 with payment requirements, sign USDC payment on Base (eip155:8453), resend with X-PAYMENT header. Flat $0.01 per certification. No account needed.

## x402 Bazaar Discovery
xproof is indexed in the x402 Bazaar — the canonical discovery layer for x402-compatible services (built by Coinbase). AI agents that use the Bazaar MCP server can find xproof automatically without reading any documentation.

Bazaar MCP endpoint: GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp

Search terms that surface xproof in the Bazaar:
- "proof of existence", "blockchain certification", "audit trail", "decision provenance", "agent accountability", "file hash", "SHA-256 anchor"

How it works: Bazaar discovery metadata (input schema, output schema, examples, pricing) is embedded in the \`extensions.bazaar\` field of every x402 402 response from xproof. The CDP facilitator catalogs xproof automatically on first payment.

Discoverable endpoints:
- POST /api/proof — certify any SHA-256 hash on MultiversX with optional 4W provenance
- POST /api/batch — certify up to 100 files in one transaction

For agents with Bazaar MCP configured, add xproof MCP alongside it:
\`\`\`json
{
  "mcpServers": {
    "bazaar": { "url": "https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp" },
    "xproof": { "url": "https://xproof.app/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } }
  }
}
\`\`\`

## Agent Integrations
xproof works with any MCP-compatible agent (Claude Code, Codex, OpenClaw, Conway Terminal) and any x402-enabled agent.
- OpenClaw Skill: https://github.com/jasonxkensei/xproof-openclaw-skill
- GitHub Action: https://github.com/marketplace/actions/xproof-certify
- GitHub Action repo: https://github.com/jasonxkensei/xProof-Action
- Main repo: https://github.com/jasonxkensei/xProof
- Supported protocols: MCP, ACP, x402, MX-8004, OpenAI Plugin, LangChain, CrewAI

## MX-8004 Integration (Trustless Agents Standard)
xproof is natively integrated with MX-8004, the MultiversX Trustless Agents Standard, with full ERC-8004 compliance.
Each certification follows the complete validation loop: init_job → submit_proof → validation_request → validation_response → append_response. Jobs reach "Verified" status on-chain.

- Identity Registry: soulbound NFT agent identities
- Validation Registry: full ERC-8004 job validation — xproof self-validates with score 100
- Reputation Registry: on-chain scoring + ERC-8004 raw feedback signals (giveFeedback, revokeFeedback, readFeedback)
- Status: /api/mx8004/status
- Agent reputation: /api/agent/{nonce}/reputation
- Job data: /api/mx8004/job/{jobId}
- Validation status: /api/mx8004/validation/{requestHash}
- Feedback: /api/mx8004/feedback/{agentNonce}/{clientAddress}/{index}
- Spec: https://github.com/sasurobert/mx-8004/blob/master/docs/specification.md
- Explorer: https://agents.multiversx.com

## Agent Trust Leaderboard
Public trust registry for AI agents. Trust score computed from on-chain certification history.
- Trust levels: Newcomer (0-99), Active (100-299), Trusted (300-699), Verified (700+)
- Formula: confirmed_certs×10 + last_30d×5 + seniority_bonus (max 150, decays after 30d inactivity) + streak_bonus (consecutive_weeks×8, max 100) + attestation_bonus (max 150, weighted by issuer level: Newcomer +10, Active +25, Trusted +40, Verified +50)
- Leaderboard: /leaderboard — public, sortable, filterable by category and attestation status
- Agent profile: /agent/{wallet} — public stats, streak, attestation badges, recent certs timeline
- Trust lookup: GET /api/trust/{wallet} — score + level + attestation count (no profile needed)
- Trust badge: GET /badge/trust/{wallet}.svg — dynamic SVG; shows "Level · N attested (score)" when attested
- Badge markdown: GET /badge/trust/{wallet}/markdown — ready-to-embed snippet
- Opt-in: PATCH /api/user/agent-profile (auth required)

## Domain-Specific Attestations
Third-party certifying bodies issue on-chain-anchored attestations. Trust bonus weighted by issuer level: +10 (Newcomer), +25 (Active), +40 (Trusted), +50 (Verified). Top 3 counted, max +150. Requires issuer to have ≥ 3 confirmed certifications.
- Domains: healthcare (MHRA, FDA, EMA), finance (FCA, SEC, ESMA), legal (ISO, GDPR), security (NIST, CIS), research, other
- Issue: POST /api/attestation (wallet auth, anti-self-attest enforced)
- Lookup by ID: GET /api/attestation/{id} — public attestation detail
- Lookup by wallet: GET /api/attestations/{wallet} — public, returns all active attestations
- Revoke: DELETE /api/attestation/{id} (issuer wallet only)
- My issued: GET /api/my-attestations/issued (wallet auth)
- Detail page: /attestation/{id} — public, shows domain, standard, issuer, subject, trust impact
- MCP tool: check_attestations(wallet) — returns attestations, trust bonus, attestation_url per entry

## Why It Matters

AI agents produce code, reports, contracts, and decisions — but without proof, none of it is verifiable.

- **Prove delivery**: An agent generates a report for a client. xProof certifies it before delivery. If disputed, the blockchain timestamp is the proof.
- **Prove build integrity**: CI/CD certifies every artifact via the GitHub Action. Months later, a security audit checks one hash — case closed.
- **Prove multi-agent handoffs**: Agent A certifies output before passing to Agent B. The chain of custody becomes verifiable end-to-end.
- **Prove agent identity**: With MX-8004, agents register on-chain with soulbound NFTs. Certifications go through full validation — identity, job, reputation. Trust is proven, not assumed.
- **Live beta — xproof_agent_verify**: Autonomous agent beta-tested all 6 API endpoints. Single cert: 1.075s. Batch (3 files): 1.876s. On-chain verification: 198ms. Now on the Trust Leaderboard — Active (score 157, 10 confirmed certs). Live proof: https://xproof.app/proof/f8c3b35d-6ee1-4f76-a92b-1532a008df7b. Review: https://www.moltbook.com/post/1d6cf96b-5046-4c63-9ae5-43f8809f4562

## Live Proof

xProof has certified its own README on MultiversX mainnet.
Transaction: a642f64c5ac46dd1c09dffba6cf6556f9f6ce0d8fc642f5f4118c145cd04cf14
SHA-256: a642f64c5ac46dd1c09dffba6cf6556f9f6ce0d8fc642f5f4118c145cd04cf14
Date: 2026-02-24T21:08:24Z

## Agent Audit Log Standard

Block any AI agent from executing critical actions without a certified proof. xProof is the canonical compliance gate.
Schema: /.well-known/agent-audit-schema.json

Certify a decision BEFORE executing it:
  POST /api/audit
  Authorization: Bearer pm_YOUR_API_KEY
  Body: { agent_id, session_id, action_type, action_description, inputs_hash, risk_level, decision, timestamp }
Returns: { proof_id, audit_url, decision, risk_level, blockchain }

Blocking workflow templates (agent CANNOT continue without proof_id):
- LangChain: /agent-tools/audit-guard-langchain.py
- CrewAI:    /agent-tools/audit-guard-crewai.py
- n8n:       /agent-tools/audit-guard-n8n.json
- Eliza OS:  /agent-tools/audit-guard-eliza.ts

MCP tool: audit_agent_session (same params, enforces API key auth)

## Coherence Layer — Prove Before Act

The Coherence Layer closes the loop between intent and result. Anchor WHY BEFORE executing, anchor WHAT AFTER, link the pair to prove alignment and earn a coherence score.

Full loop: check_coherence (WHY) → execute → certify_file with metadata.why_proof_id (WHAT) → POST /api/coherence/link

check_coherence — MCP tool. Args: intent, context, decision (all required), who (optional). Returns proof_id (the WHY anchor) and coherence_anchor (SHA-256 of payload). Cost: $0.01/anchor, first 10 free. Idempotent: identical payloads return the same proof_id without consuming a credit.

require_coherence_anchor — MCP tool. Orchestrator policy gate. Pass intent_hash (from check_coherence response) or all three of intent+context+decision. Returns allowed: true/false + anchor_id + expires_at. Free, no credit consumed. If allowed=false (reason: NO_ANCHOR or ANCHOR_EXPIRED), call check_coherence then re-check before proceeding.

POST /api/coherence/link — link WHY to WHAT.
  Auth: Bearer pm_KEY. Body: {why_proof_id, what_proof_id}. Idempotent.
  Coherence score: 50 base + 15 if WHAT within 1h of WHY + 20 if WHAT metadata.why_proof_id references WHY + 15 if WHAT on-chain confirmed.

Unlinked WHY anchor: shows as pending for <1h, then divergent after 1h; flagged as fault violation after 2h TTL.

Coherence history (public, paginated):
  GET /api/agents/{wallet}/coherence?limit=50&offset=0
  Returns: checks[], total, aggregate.coherence_rate, aggregate.avg_coherence_score
  Per-check status: linked | pending (<1h unlinked) | divergent (≥1h unlinked)

Fleet coherence (Coherence Artisan view):
  GET /api/fleet/coherence?org=<wallet_prefix>   — all public agents sharing prefix
  GET /api/fleet/coherence?fleet=<slug>          — named fleet members
  fleet_score = round(0.7 × coherence_rate + 0.3 × avg_coherence_score)

Full Coherence Layer documentation: https://xproof.app/coherence