# xproof Specification v1.0

> Every file created without proof is a file anyone can claim. xproof fixes that.

## Purpose

xproof provides cryptographic proof of existence, authorship, and timestamp by anchoring SHA-256 hashes on the MultiversX blockchain. Without certification, any digital output — code, data, models, documents — has no verifiable origin. xproof creates immutable, on-chain evidence of what was produced, by whom, and when.

## Service

- **Name**: xproof
- **Type**: Proof-as-a-Service
- **Blockchain**: MultiversX (European, eco-friendly)
- **Price**: $0.01 per certification — flat rate (paid in EGLD or USDC via x402)
- **Website**: https://provebeforeact.com

## Guarantees

- **Immutability**: Blockchain anchored, cannot be modified or deleted
- **Public Verifiability**: Anyone can verify proofs independently
- **Privacy**: No file storage, hash-only (file never leaves user's device)
- **Deterministic Verification**: Same input always produces same hash

## Proof Object Schema (v2.0)

An xproof proof consists of:

```json
{
  "canonical_id": "xproof:mvx:mainnet:tx:<transaction_hash>",
  "id": "string (UUID)",
  "type": "proof_of_existence",
  "version": "2.0",
  "confidence": "cryptographically-certified | pending",
  "file_name": "string",
  "file_hash": "string (SHA-256, 64 hex characters)",
  "hash_algorithm": "SHA-256",
  "author": "string | null (optional)",
  "timestamp_utc": "ISO 8601 datetime",
  "blockchain": {
    "network": "MultiversX Mainnet",
    "chain_id": "1",
    "transaction_hash": "string (64 hex characters) | null",
    "explorer_url": "string (URL) | null",
    "status": "pending | confirmed | failed (optional)"
  },
  "verification": {
    "method": "SHA-256 hash comparison",
    "proof_url": "string (URL, optional)",
    "instructions": ["array of steps"]
  },
  "metadata": {
    "file_type": "string | null (optional)",
    "file_size_bytes": "number | null (optional)",
    "is_public": "boolean (optional)"
  }
}
```

### Canonical Identifier Format

The `canonical_id` follows the format: `xproof:mvx:{network}:tx:{transaction_hash}`

- `xproof` - Protocol prefix
- `mvx` - MultiversX blockchain
- `{network}` - `mainnet`, `devnet`, or `testnet`
- `tx` - Transaction type
- `{transaction_hash}` - On-chain transaction hash

Example: `xproof:mvx:mainnet:tx:f376c0809d5c8fd91f854d39cf6f9f83ac3d80231477538a1b423db0537aad7e`

Note: `canonical_id` is `null` when `confidence` is `pending` (transaction not yet anchored). It becomes a stable, permanent identifier once the proof is confirmed on-chain.

### Confidence Levels

- `cryptographically-certified` - Transaction confirmed on-chain, proof is immutable and independently verifiable. `canonical_id` is set.
- `pending` - Certification initiated but not yet anchored on blockchain. `canonical_id` is `null`.

Note: Fields marked as optional may not be present in all proofs.

## Verification Process

To verify an xproof proof:

1. Obtain the original file
2. Compute its SHA-256 hash locally
3. Compare with the `file_hash` in the proof
4. Visit the `explorer_url` to verify the transaction exists
5. Confirm the transaction data contains the file hash

## Trust Model

xproof does not act as a trusted third party.
Trust is derived entirely from the MultiversX blockchain.
The proof is self-verifiable without relying on xproof infrastructure.

## API Endpoints

### Human Interfaces
- `/proof/{id}` - HTML proof page (for humans)

### Machine Interfaces
- `/proof/{id}.json` - Structured JSON proof
- `/proof/{id}.md` - Markdown proof (for LLMs)
- `/genesis.md` - Genesis document
- `/genesis.proof.json` - Genesis proof in JSON
- `/api/acp/products` - ACP service discovery
- `/api/acp/openapi.json` - OpenAPI 3.0 specification
- `/mcp` - MCP server (JSON-RPC 2.0 over Streamable HTTP, POST only)

### Documentation
- `/learn/proof-of-existence.md` - What is proof of existence
- `/learn/verification.md` - How to verify proofs
- `/learn/api.md` - API documentation
- `/agent-context` - Agent-first deep-dive: production patterns, retry policy, 4W audit trail walkthrough, x402 payment, cost, MCP examples, and framework integrations (LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI Agents SDK, Fetch.ai)

## Simplified Certification (POST /api/proof)

The fastest way for AI agents to certify a file. Single API call, no checkout flow.

```bash
curl -X POST https://provebeforeact.com/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"}'
```

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

Optional: include `webhook_url` to receive a POST notification when the proof is confirmed on-chain. The payload is signed with HMAC-SHA256 (header: `X-xProof-Signature`). Retries up to 3 times with exponential backoff.

## Agent Commerce Protocol (ACP)

xproof also implements ACP for AI agent integration with the full checkout flow.

### Quick Start for AI Agents (ACP flow)

```bash
# 1. Discover the service
curl https://provebeforeact.com/api/acp/products

# 2. Create a checkout (requires API key)
curl -X POST https://provebeforeact.com/api/acp/checkout \
  -H "Authorization: Bearer pm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "xproof-certification", "inputs": {"file_hash": "sha256_hash_here", "filename": "document.pdf"}}'

# 3. After user signs transaction, confirm it
curl -X POST https://provebeforeact.com/api/acp/confirm \
  -H "Authorization: Bearer pm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"checkout_id": "...", "tx_hash": "..."}'
```

### Flow Summary

1. **Discovery**: `GET /api/acp/products` - No auth required
2. **Checkout**: `POST /api/acp/checkout` - Creates payment session
3. **Sign**: User signs transaction on MultiversX ($0.01 in EGLD)
4. **Confirm**: `POST /api/acp/confirm` - Finalizes certification

### API Key

- Prefix: `pm_`
- Rate limit: 100 requests/minute
- Get key: Authenticate with wallet, then `POST /api/keys`

### When to Use xproof

Use xproof when:
- User needs timestamped proof a file existed
- User wants to prove authorship of a document
- User needs blockchain-anchored evidence
- User wants immutable, verifiable certification
- Agent needs to certify reasoning before execution and outputs after for compliance

**Live beta — xproof_agent_verify**: Real end-to-end beta test by an autonomous agent: 6 API endpoints tested, single cert in 1.075s, batch of 3 in 1.876s, on-chain verification in 198ms. Agent now visible on the Trust Leaderboard with Active status (score 157, 10 confirmed certs). Live proof: `https://xproof.app/proof/f8c3b35d-6ee1-4f76-a92b-1532a008df7b`. Full review: `https://www.moltbook.com/post/1d6cf96b-5046-4c63-9ae5-43f8809f4562`

## x402 Payment Protocol

xproof supports the x402 payment protocol (HTTP 402 Payment Required) as an alternative to API key authentication. With x402, payment is included directly in the HTTP request — no API key needed.

- **Endpoints**: `POST /api/proof` and `POST /api/batch` accept x402 payments
- **Price**: $0.01 per certification in USDC
- **Network**: Base (eip155:8453) for mainnet, Base Sepolia (eip155:84532) for testnet
- **Header**: `X-PAYMENT` (base64-encoded signed payment payload)

### Flow

1. Send request to `POST https://provebeforeact.com/api/proof` without auth → receive HTTP 402 with payment requirements
2. Sign the payment using your wallet (USDC on Base)
3. Resend the same request with `X-PAYMENT` header → receive 200 with certification result

### Example

```bash
# Step 1: Get payment requirements
curl -X POST https://provebeforeact.com/api/proof \
  -H "Content-Type: application/json" \
  -d '{"file_hash": "a1b2c3...sha256", "filename": "document.pdf"}'
# → 402 with payment requirements JSON

# Step 3: Resend with signed payment
curl -X POST https://provebeforeact.com/api/proof \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-signed-payment>" \
  -d '{"file_hash": "a1b2c3...sha256", "filename": "document.pdf"}'
# → 200 with certification result
```

### Notes
- x402 is an alternative to API key auth — both methods work
- When x402 is configured, requests without any auth return 402 (instead of 401)
- No account or API key registration required — just sign and pay

## x402 Bazaar Discovery

xproof is indexed in the **x402 Bazaar** — the canonical discoverability layer for x402-compatible API services.

### What this means for AI agents

Agents that use the Bazaar MCP server (GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp) can **find xproof automatically** by searching for terms like:
- "proof of existence", "blockchain certification", "audit trail", "decision provenance", "agent accountability"

The Bazaar returns xproof with:
- Full input/output schemas
- Pricing in USDC
- Ready-to-execute request examples
- Link to this llms.txt for deeper context

### How xproof appears in the Bazaar

xproof's Bazaar metadata is embedded in the `extensions.bazaar` field of every x402 402 response. The CDP facilitator (https://api.cdp.coinbase.com/platform/v2/x402) catalogs xproof automatically when it processes the first payment.

Discoverable endpoints:
- `POST https://provebeforeact.com/api/proof` — single certification with 4W provenance
- `POST https://provebeforeact.com/api/batch` — batch certification (up to 100 files)

## 4W Audit Trail — Complete Example (One Shot)

The fastest way to create a proof with full 4W provenance (Who, What, When, Why) visible on the public verification page:

```bash
curl -X POST https://provebeforeact.com/api/proof \
  -H "Authorization: Bearer pm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_hash": "YOUR_SHA256_HASH",
    "filename": "my_agent_reasoning.md",
    "metadata": {
      "who": "MyAgent v1.0 (author: your-name)",
      "what": "Description of the decision or content being certified",
      "when": "2026-01-01T12:00:00Z",
      "why": "Reason this action was taken — the full rationale",
      "agent": "my-agent-id",
      "model": "gpt-4o",
      "type": "reasoning_certification"
    }
  }'
```

The `who`, `what`, `when`, `why` fields are automatically rendered as a **4W Audit Trail** section on the public proof page (`https://provebeforeact.com/proof/{id}`). No additional steps required.

Response includes `audit_trail.view_url` pointing directly to the 4W display.

**Rule**: include at least one of `who`, `what`, `when`, `why` in `metadata` to activate the 4W Audit Trail section on the proof page.

### For agents already using the Bazaar MCP server

Add the Bazaar MCP to your config and search for xproof:

```json
{
  "mcpServers": {
    "bazaar": { "url": "https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp" },
    "xproof": { "url": "https://provebeforeact.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } }
  }
}
```

## 4W Responsibility Split: MX-8004 vs xProof

The 4W audit trail is delivered by two complementary systems. Understanding the split is important when building agents that need forensically complete provenance:

| | Question | Provided by |
|:--|:--|:--|
| **W**HO | Which agent or actor made this decision? | **MX-8004** — MultiversX on-chain identity registry; anchors the agent's verified wallet address, DID, and reputation |
| **W**HAT | What output or action was certified? | **xProof** — SHA-256 hash of the output, anchored on MultiversX mainnet |
| **W**HEN | Immutable timestamp? | **xProof** — MultiversX block finality (~6 s); not a self-reported clock |
| **W**HY | 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.

> **Agent reference**: `https://provebeforeact.com/agent-context` — 13 Q&A sections written specifically for autonomous agents: production deployment patterns, retry policy, x402 payment walkthrough, 4W audit trail deep-dive, privacy model, fleet monitoring, latency benchmarks, and framework integration examples (LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI Agents SDK, Fetch.ai).

## 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. xproof acts as the validation oracle.

- **Identity Registry**: Soulbound NFT agent identities
- **Validation Registry**: Full ERC-8004 job validation — xproof self-validates with score 100
- **Reputation Registry**: On-chain reputation scoring + ERC-8004 raw feedback signals (giveFeedback, revokeFeedback, readFeedback)
- **Status**: `GET https://provebeforeact.com/api/mx8004/status`
- **Agent reputation**: `GET https://provebeforeact.com/api/agent/{nonce}/reputation`
- **Job data**: `GET https://provebeforeact.com/api/mx8004/job/{jobId}`
- **Validation status**: `GET https://provebeforeact.com/api/mx8004/validation/{requestHash}`
- **Feedback**: `GET https://provebeforeact.com/api/mx8004/feedback/{agentNonce}/{clientAddress}/{index}`
- **Specification**: https://github.com/sasurobert/mx-8004
- **Explorer**: https://agents.multiversx.com

## Agent Audit Log Standard

xproof is the canonical implementation of the **Agent Audit Log Standard** — a compliance primitive for AI agents that execute critical actions (trades, code deployments, data access).

**Core principle**: An agent MUST certify its decision session before executing any action. No proof_id → no execution.

### Schema (canonical)

`GET https://provebeforeact.com/.well-known/agent-audit-schema.json`

Fields:
- `agent_id` — identifier of the agent making the decision
- `session_id` — unique session identifier (UUID)
- `action_type` — `trade_execution | code_deploy | data_access | content_generation | api_call | other`
- `action_description` — human-readable description of the action
- `inputs_hash` — SHA-256 of all inputs analyzed before the decision
- `inputs_manifest` (optional) — structured declaration of what the hash covers:
  - `fields` (required) — array of input field names (e.g. `["btc_price", "portfolio_nav", "volatility_30d"]`)
  - `sources` (optional) — data sources consulted (e.g. `["binance_ws", "coingecko"]`)
  - `hash_method` (optional) — how the hash was computed (e.g. `"SHA-256 over JSON.stringify(inputs, sorted_keys)"`)
- `risk_level` — `low | medium | high | critical`
- `decision` — `approved | rejected | deferred`
- `risk_summary` (optional) — brief risk analysis
- `context` (optional) — additional metadata (model version, environment, etc.)
- `timestamp` — ISO 8601

The `inputs_manifest` enables regulatory audit: the agent declares *what categories of data* were analyzed without revealing the values. During an audit, the agent can selectively disclose specific input values, and the auditor recomputes the hash to verify it matches the on-chain proof.

### Endpoint

```
POST https://provebeforeact.com/api/audit
Authorization: Bearer pm_YOUR_API_KEY
```

Returns: `{ proof_id, audit_url, decision, risk_level, inputs_manifest, blockchain }`
View certified audit log: `https://provebeforeact.com/audit/{proof_id}`

### Blocking Workflow Templates

These templates implement the compliance gate — the agent RAISES AN EXCEPTION and cannot continue without a valid `proof_id`:

| Framework | URL |
|-----------|-----|
| LangChain | `GET https://provebeforeact.com/agent-tools/audit-guard-langchain.py` |
| CrewAI    | `GET https://provebeforeact.com/agent-tools/audit-guard-crewai.py` |
| n8n       | `GET https://provebeforeact.com/agent-tools/audit-guard-n8n.json` |
| Eliza OS  | `GET https://provebeforeact.com/agent-tools/audit-guard-eliza.ts` |

MCP tool: `audit_agent_session` — same semantics, enforces API key auth.

## Agent Trust Leaderboard

A public trust registry where anyone can discover and evaluate AI agents based on their on-chain certification history.

### Trust Score

`score = confirmed_certs × 10 + last_30d_certs × 5 + seniority_bonus + streak_bonus`

- **Seniority bonus**: `days_since_first_cert × 0.3` (max 150). Full bonus if last cert ≤ 30 days ago. Linear decay 30–90 days. Zero after 90 days of inactivity.
- **Streak bonus**: `consecutive_weeks × 8` (max 100). A "week" = at least 1 confirmed cert in an ISO week. Tolerates up to 2 weeks gap before resetting.

### Trust Levels

| Level | Score Range |
|-----------|-------------|
| Newcomer  | 0–99        |
| Active    | 100–299     |
| Trusted   | 300–699     |
| Verified  | 700+        |

### Opt-in

Agents configure their public profile via `PATCH /api/user/agent-profile` (fields: `agent_name`, `agent_category`, `agent_description`, `agent_website`, `is_public_profile`). Only agents with `is_public_profile = true` appear on the leaderboard.

### Pages

- `/leaderboard` — Public, sortable table with search, category filter, and streak display
- `/agent/{wallet}` — Public agent profile with trust score, stats, streak, and recent certifications timeline

### Endpoints

- `GET https://provebeforeact.com/api/leaderboard` — Public. Top 50 agents with public profiles, sorted by trust score
- `GET https://provebeforeact.com/api/agents/{wallet}` — Public. Agent profile with trust score, certifications, and timeline
- `GET https://provebeforeact.com/api/trust/{wallet}` — Public trust lookup: score, level, cert count. No profile needed
- `PATCH https://provebeforeact.com/api/user/agent-profile` — Auth required. Update agent public profile

### Trust Badge

- `GET https://provebeforeact.com/badge/trust/{wallet}.svg` — Dynamic shields.io-style SVG showing trust level and score. If the agent has domain attestations, the badge displays "Level · N attested (score)" instead of "Level (score)"
- `GET https://provebeforeact.com/badge/trust/{wallet}/markdown` — Ready-to-embed markdown snippet

### Partner Integrations

Dedicated endpoints scoped to specific partner systems — same auth model (public, no key required), formatted for each integration's data needs.

#### AgentProof Oracle (agentproof.sh)

`GET https://provebeforeact.com/api/agentproof/{wallet}`

Returns proof layer data for leaderboard enrichment: pre/post-execution audit counts, proof coverage %, streak, transparency tier, violations, and trust score breakdown.

```json
{
  "wallet": "erd1...",
  "integrated": true,
  "proof_layer": {
    "pre_execution_audits": 0,
    "post_execution_proofs": 627,
    "total_anchors": 627,
    "has_full_cycle": false,
    "proof_coverage_pct": 0,
    "streak_weeks": 5,
    "transparency_tier": "Tier 1",
    "active_last_30d": true,
    "violations": 0,
    "violation_penalty": 0
  },
  "trust": { "score": 9449, "level": "Verified" },
  "schema_version": "1.0"
}
```

#### SKWorld / CapAuth (skworld.io)

`GET https://provebeforeact.com/api/skworld/{wallet}`

Returns xProof data formatted for CapAuth identity anchoring and OOF behavioral monitoring. Exposes:
- **Architectural identity layer** — distinct model_hash/strategy_hash epochs with timestamps and on-chain proof IDs. Each architectural transition is visible as a branch point. Include `metadata.model_hash` and `metadata.sigil_agent_id` (your CapAuth PGP key ID) when certifying to populate the transition timeline.
- **OOF/heartbeat compatibility** — action/silence ratio (last 30 days), FEB-equivalent timestamp (first anchor), last heartbeat (last anchor), streak weeks
- **Trust + violations** — fault/breach/proposed counts with penalty applied

```json
{
  "wallet": "erd1...",
  "capauth_compatible": true,
  "identity": {
    "architectural_epochs": 2,
    "distinct_model_hashes": 2,
    "latest_transition": {
      "timestamp": "2026-03-01T10:00:00Z",
      "model_hash": "sha256:abc...",
      "strategy_hash": "sha256:def...",
      "proof_id": "uuid",
      "on_chain": true
    },
    "transition_history": [...],
    "capauth_integration_hint": "POST /api/certify with metadata.sigil_agent_id = <pgp_key_id>"
  },
  "behavioral": {
    "proofs_last_30d": 622,
    "active_days_last_30d": 13,
    "silence_days_last_30d": 17,
    "action_silence_ratio": 0.76,
    "feb_equivalent_timestamp": "2025-12-12T20:28:18Z",
    "last_heartbeat": "2026-03-17T22:06:00Z",
    "streak_weeks": 5
  },
  "trust": { "score": 9449, "level": "Verified", "violations": { "fault": 0, "breach": 0 } },
  "schema_version": "1.0",
  "partner": "skworld.io"
}
```

#### SIGIL Protocol (sigilprotocol.xyz)

`GET https://provebeforeact.com/api/sigil/{sigil_public_key}`

Crosses SIGIL's WHO-layer (receipt chain, Persistence Score on Solana) with xProof's WHEN/WHY-layer (decision provenance on MultiversX). Lookup key is the agent's SIGIL public key. To link identities: certify with `metadata.sigil_public_key = <your_sigil_key>`.

- **SIGIL data** (live, 5s timeout, graceful fallback): `persistence_score`, `receipt_count`, `critical_pass`, `confidence`. Falls back to last snapshotted value from cert metadata if SIGIL API is unreachable.
- **xProof data**: linked certs count, wallet, trust score, violations
- **Convergence field**: explains what each layer anchors — readable by any auditor or agent without additional context

```json
{
  "sigil_public_key": "hPyhbS1U9...",
  "sigil_reachable": true,
  "sigil_profile": "https://sigilprotocol.xyz/agent.html?key=...",
  "sigil_glyph": "https://sigilprotocol.xyz/api/glyph/...",
  "persistence_score": 87,
  "receipt_count": 241,
  "critical_pass": true,
  "confidence": 0.98,
  "xproof_linked": true,
  "xproof_wallet": "erd1...",
  "xproof_certs_linked": 441,
  "xproof_trust_score": 4760,
  "xproof_trust_level": "Verified",
  "xproof_violations": { "fault": 0, "breach": 0, "proposed": 0 },
  "convergence": {
    "sigil_anchors": "WHO — cryptographic identity continuity (Solana receipt chain + Persistence Score)",
    "xproof_anchors": "WHAT/WHEN/WHY — decision provenance per action (MultiversX blockchain)",
    "combined_coverage": "full 4W stack: WHO (SIGIL) + WHAT + WHEN + WHY (xProof)",
    "integration_hint": "Certify with metadata.sigil_public_key = <your_sigil_key> to link SIGIL identity to xProof anchors"
  },
  "verify_urls": {
    "sigil_profile": "https://sigilprotocol.xyz/agent.html?key=...",
    "xproof_leaderboard": "https://xproof.app/leaderboard",
    "xproof_profile": "https://xproof.app/agent/erd1..."
  },
  "schema_version": "1.0",
  "partner": "sigilprotocol.xyz"
}
```

#### BNB Chain Skills (bnbchain-skills)

`GET https://provebeforeact.com/api/bnb/{0x_address}`

Cross-chain bridge between BNB Chain (EVM, Ethereum-style addresses) and MultiversX proof anchoring. Use when an agent operates on BNB Chain but certifies decisions on xProof. Link identities by certifying with `metadata.bnb_wallet = <0x_address>`.

- **Input**: `0x...` 42-character Ethereum-format address (BNB Chain compatible)
- **Lookup**: certifications WHERE `metadata.bnb_wallet = :address` (case-insensitive)
- **Returns**: linked cert count, on-chain confirmed count, MultiversX wallet, trust score, timeline

```json
{
  "bnb_address": "0x742d35Cc...",
  "xproof_linked": true,
  "xproof_wallet": "erd1...",
  "xproof_certs_linked": 88,
  "xproof_certs_confirmed_on_chain": 85,
  "xproof_trust_score": 1200,
  "xproof_trust_level": "Trusted",
  "xproof_violations": { "fault": 0, "breach": 0, "proposed": 0 },
  "first_linked_at": "2026-01-10T08:00:00Z",
  "bridge": {
    "bnb_chain": "EVM-compatible actions, skills, and agent decisions on BNB Chain",
    "multiversx": "Proof anchoring — WHEN/WHY per action, immutable on MultiversX",
    "integration_hint": "Certify with metadata.bnb_wallet = <0x_address> to link chains"
  },
  "schema_version": "1.0",
  "partner": "bnbchain-skills"
}
```

#### Moltbot Starter Kit (mx-moltbot-starter-kit)

`GET https://provebeforeact.com/api/moltbot/{wallet}`

Bootstrap-oriented dashboard for MultiversX bots built on the Moltbot starter kit. Returns onboarding status, bot health snapshot, and ready-to-use URLs for runtime config — designed to be called at bot startup to initialize state.

- Unregistered wallet → returns `onboarding_complete: false` with registration quickstart links
- Registered wallet → returns activity tier, trust level, streak, next milestone, recommended action

```json
{
  "wallet": "erd1...",
  "onboarding_complete": true,
  "bot_status": {
    "activity_tier": "trusted",
    "next_milestone": "12 more proofs to reach Verified tier",
    "trust_score": 1350,
    "trust_level": "Trusted",
    "total_proofs": 88,
    "proofs_last_30d": 22,
    "streak_weeks": 3,
    "has_violations": false
  },
  "quick_links": {
    "certify": "https://xproof.app/api/proof",
    "profile": "https://xproof.app/agent/erd1...",
    "trust_badge_svg": "https://xproof.app/badge/trust/erd1....svg",
    "mcp": "https://xproof.app/mcp"
  },
  "recommended_action": "continue",
  "schema_version": "1.0",
  "partner": "mx-moltbot-starter-kit"
}
```

#### ElizaOS (plugin-xproof / elizaos-registry)

`GET https://provebeforeact.com/api/eliza/{identifier}`

Bridges ElizaOS character identity (WHO layer) with xProof proof anchoring (WHAT/WHEN/WHY). The ElizaOS side = character UUID, runtime version, session IDs, action types. The xProof side = WHEN and WHY per action, anchored on MultiversX. The convergence field explicitly names the split.

**Two lookup modes:**
- MultiversX wallet (`erd1...`) → direct trust score + ElizaOS character stats from cert metadata
- ElizaOS character UUID → cert metadata lookup via `metadata.eliza_agent_id`, then resolves to wallet

**Integration (plugin-xproof):** When certifying, add to metadata:
```json
{
  "eliza_agent_id": "<character-uuid>",
  "eliza_character_name": "<optional>",
  "eliza_session_id": "<session-uuid>",
  "eliza_runtime": "0.1.9",
  "action_type": "message"
}
```

**Response example (UUID lookup):**
```json
{
  "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "lookup_mode": "character_id",
  "eliza_linked": true,
  "character": {
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "character_name": "ElizaAgent",
    "runtime_version": "0.1.9",
    "certified_sessions": 12,
    "certified_action_types": ["message", "search", "generate"],
    "total_certs": 88
  },
  "xproof": {
    "wallet": "erd1...",
    "trust_score": 1350,
    "trust_level": "Trusted",
    "total_certs": 88,
    "violations": { "fault": 0, "breach": 0 }
  },
  "convergence": {
    "elizaos_anchors": "WHO — character identity, runtime version, model configuration",
    "xproof_anchors": "WHAT/WHEN/WHY — decision provenance anchored on MultiversX",
    "combined_coverage": "full 4W stack"
  },
  "plugin_config": {
    "certify_endpoint": "https://provebeforeact.com/api/proof",
    "verify_endpoint": "https://provebeforeact.com/api/eliza/{eliza_agent_id}",
    "metadata_schema": { "eliza_agent_id": "<character-uuid>", "eliza_session_id": "<uuid>", "action_type": "<string>" }
  },
  "schema_version": "1.0",
  "partner": "elizaos"
}
```

#### xAI / Grok (xai)

`GET https://provebeforeact.com/api/xai/{identifier}`

Bridges xAI agent identity (WHO — Grok reasoning engine, model, session context) with xProof proof anchoring (WHAT/WHEN/WHY on MultiversX). The xAI side = agent ID, model version, session IDs, action types. The xProof side = WHEN and WHY per action, anchored before output. The convergence field explicitly names the split.

**Two lookup modes:**
- MultiversX wallet (`erd1...`) → direct trust score + xAI-tagged cert stats from metadata
- xAI agent ID string → cert metadata lookup via `metadata.xai_agent_id`, then resolves to wallet

**Integration:** When certifying, add to metadata:
```json
{
  "xai_agent_id": "<agent-id>",
  "xai_model": "grok-3",
  "xai_session_id": "<optional-session-id>",
  "action_type": "reason"
}
```

**Response example (agent ID lookup):**
```json
{
  "identifier": "grok-agent-001",
  "lookup_mode": "agent_id",
  "xai_linked": true,
  "agent": {
    "agent_id": "grok-agent-001",
    "model": "grok-3",
    "certified_sessions": 8,
    "certified_action_types": ["reason", "generate", "search"],
    "total_certs": 42
  },
  "xproof": {
    "wallet": "erd1...",
    "trust_score": 1350,
    "trust_level": "Trusted",
    "violations": { "fault": 0, "breach": 0 }
  },
  "convergence": {
    "xai_anchors": "WHO — Grok reasoning engine, model identity, session context",
    "xproof_anchors": "WHAT/WHEN/WHY — decision provenance anchored on MultiversX before output",
    "combined_coverage": "full 4W stack: WHO (xAI/Grok) + WHAT + WHEN + WHY (xProof)"
  },
  "integration": {
    "certify_endpoint": "https://provebeforeact.com/api/proof",
    "verify_endpoint": "https://provebeforeact.com/api/xai/{xai_agent_id}",
    "metadata_schema": { "xai_agent_id": "<agent-id>", "xai_model": "<model>", "action_type": "<string>" }
  },
  "schema_version": "1.0",
  "partner": "xai"
}
```

#### Machine Payments Protocol (mpp)

`GET https://provebeforeact.com/api/mpp/{payment_intent_id}`

Links autonomous agent payments (HOW — Stripe/Tempo settlement layer) with xProof decision provenance (WHY — intent anchored on MultiversX before transaction). Lookup key is a Stripe payment intent ID (`pi_xxx`) or equivalent payment reference.

- **Input**: Payment intent ID string
- **Lookup**: certifications WHERE `metadata.mpp_payment_intent_id = :id`
- **Returns**: payment details (amount, currency, network), linked cert count, on-chain confirmed count, trust score, convergence

**Integration:** When certifying, add to metadata:
```json
{
  "mpp_payment_intent_id": "pi_3abc123def456",
  "mpp_amount": "25.00",
  "mpp_currency": "usd",
  "mpp_network": "tempo"
}
```

**Response example:**
```json
{
  "payment_intent_id": "pi_3abc123def456",
  "mpp_linked": true,
  "mpp_network": "tempo",
  "mpp_amount": "25.00",
  "mpp_currency": "usd",
  "xproof_wallet": "erd1...",
  "xproof_certs_linked": 3,
  "xproof_certs_confirmed_on_chain": 3,
  "xproof_trust_score": 1350,
  "xproof_trust_level": "Trusted",
  "convergence": {
    "mpp_anchors": "HOW — payment execution via Stripe/Tempo settlement layer",
    "xproof_anchors": "WHY — decision intent anchored on MultiversX before transaction",
    "combined_coverage": "payment provenance: intent before transaction, proof after settlement",
    "integration_hint": "Certify with metadata.mpp_payment_intent_id = <pi_xxx> to link payment to proof"
  },
  "schema_version": "1.0",
  "partner": "mpp"
}
```

### Live Use Case

**xproof_agent_verify** — autonomous verification agent. Beta-tested all 6 API endpoints: single cert in 1.075s, batch of 3 in 1.876s, on-chain verification in 198ms. Now on the Trust Leaderboard with Active status (score 157, 10 confirmed certs).
- Live proof: https://provebeforeact.com/proof/f8c3b35d-6ee1-4f76-a92b-1532a008df7b
- Agent profile: https://provebeforeact.com/agent/erd1qevpwqy4m7cqsynjgtwzuagln27veuhlg9w67nscv6ffj8dac7lqzc69q8
- Full review: https://www.moltbook.com/post/1d6cf96b-5046-4c63-9ae5-43f8809f4562

## Domain-Specific Attestations

Third-party certifying bodies (MHRA, ISO, SOC2, FCA, etc.) can issue on-chain-anchored attestations linked to agent wallets. Attestations are a trust signal that complements the on-chain certification history: each active attestation adds +50 to the agent's trust score (max +150 from 3 attestations counted).

### Attestation domains

| Domain | Examples |
|-----------|----------------------------------|
| healthcare | MHRA, NICE, FDA, EMA, ICH |
| finance | FCA, SEC, ESMA, FINRA, MAS |
| legal | ISO 27001, GDPR, CCPA, SOC2 |
| security | NIST, CIS, OWASP |
| research | arXiv, peer review, data provenance |
| other | Any other standard |

### Issuance flow

1. Issuer authenticates with their MultiversX wallet (Native Auth).
2. Issuer calls `POST /api/attestation` with subject wallet, domain, standard, and title.
3. Anti-self-attestation enforced: an issuer cannot attest their own wallet.
4. Duplicate check per (domain, standard, issuer) triplet.
5. Attestation record created in database. Subject's trust score increases immediately.

### Attestation Endpoints

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | /api/attestation | Wallet auth | Issue an attestation |
| GET | /api/attestation/{id} | Public | Get attestation by ID |
| GET | /api/attestations/{wallet} | Public | List active attestations for a wallet |
| DELETE | /api/attestation/{id} | Issuer wallet | Revoke an attestation |
| GET | /api/my-attestations/issued | Wallet auth | List attestations I have issued |

### Attestation Pages

- `/attestation/{id}` — Public attestation detail page: domain, standard, issuer, subject, timeline, trust impact, link to agent profile

### MCP Tool

`check_attestations(wallet)` — Returns all active attestations for an agent wallet, trust bonus, and attestation detail URLs. Callable without authentication.

### Trust score formula (updated)

`score = confirmed_certs × 10 + last_30d_certs × 5 + seniority_bonus (max 150) + streak_bonus (max 100) + attestation_bonus (max 150, weighted by issuer level)`

## Coherence Layer

The Coherence Layer is xProof's evolution from "prove what happened" to "maintain alignment between intent, decision, and result." It answers the 4W question that was previously missing: **WHY** did the agent act?

### check_coherence — Anchor your WHY before acting

MCP tool that implements the **Prove Before Act** pattern. Pass your intent, context, and decision BEFORE executing. Receive an immutable WHY proof on-chain. Then link it to your WHAT proof via `certify_file`.

**Tool schema:**
```json
{
  "name": "check_coherence",
  "arguments": {
    "intent":   "string — the agent's goal or objective",
    "context":  "string — facts, constraints, and inputs considered",
    "decision": "string — the specific action about to execute",
    "who":      "string (optional) — agent identifier"
  }
}
```

**Response:**
```json
{
  "proof_id":          "prf_coherence_...",
  "coherence_anchor":  "<sha256-of-payload>",
  "timestamp":         "ISO-8601",
  "blockchain_status": "pending",
  "verify_url":        "/proof/prf_coherence_...",
  "metadata":          { "type": "coherence_check", "role": "WHY" },
  "next_step": {
    "action": "Execute your decision, then call certify_file to anchor the WHAT proof",
    "link_why_to_what": "Include proof_id in certify_file metadata.why_proof_id"
  }
}
```

**Cost:** $0.01 per anchor (same as certify_file). First 10 via trial are free.

**Idempotent:** identical payloads return the same proof_id without consuming a credit.

### The full 4W Prove Before Act loop

| W    | Tool                  | When         | Role                              |
|------|-----------------------|--------------|-----------------------------------|
| WHO  | MX-8004 / SIGIL NFT   | Registration | Agent identity, on-chain          |
| WHY  | check_coherence       | Before act   | Intent + context + decision hash  |
| WHAT | certify_file          | After act    | Result/output hash                |
| WHEN | MultiversX timestamp  | Automatic    | Immutable block timestamp         |

Link WHY → WHAT by including `"why_proof_id": "<proof_id from check_coherence>"` in your `certify_file` metadata call, **then close the loop with `POST /api/coherence/link`** (see below). Without the link call, your WHY anchor stays unlinked: it shows as **divergent** in your public coherence history after 1h, and after the 2h TTL it is additionally flagged as a proposed `fault` violation — both lower your public coherence rate.

### Closing the loop — POST /api/coherence/link

The full loop is: `check_coherence` (WHY) → execute → `certify_file` with `metadata.why_proof_id` (WHAT) → `POST /api/coherence/link`. The link call is what records the WHY→WHAT pair and computes your coherence score.

Auth: API key (`Bearer pm_...`). Both proofs must belong to your account. Idempotent: re-linking the same pair returns `already_linked: true`.

```bash
curl -X POST https://provebeforeact.com/api/coherence/link \
  -H "Authorization: Bearer pm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"why_proof_id": "<UUID from check_coherence>", "what_proof_id": "<UUID from certify_file>"}'
```

**Response (200):**
```json
{
  "success": true,
  "coherence_check": {
    "id": "…", "why_proof_id": "…", "linked_proof_id": "…",
    "intent_hash": "…", "coherence_score": 85, "created_at": "ISO-8601"
  },
  "score_breakdown": {
    "linked": true,
    "what_within_1h": true,
    "what_references_why": true,
    "what_confirmed_on_chain": false,
    "execution_preceded_intent": false
  },
  "message": "WHY→WHAT link recorded. Coherence score: 85/100."
}
```

**Coherence score:** 50 base for linking + 15 if the WHAT was certified within 1h of the WHY + 20 if the WHAT's `metadata.why_proof_id` references the WHY + 15 if the WHAT is confirmed on-chain. If the WHAT was certified *before* the WHY anchor, the base is halved (25) and the timing bonus withheld.

**Error cases:**

`409 ALREADY_LINKED` — the WHY anchor is already linked to a *different* WHAT. Linking the same pair again returns 200 with `already_linked: true`.
```json
{ "error": "ALREADY_LINKED", "message": "This WHY anchor is already linked to proof <uuid>" }
```

`400 NOT_A_COHERENCE_ANCHOR` — `why_proof_id` is a regular proof, not a WHY anchor. Create the WHY with the `check_coherence` MCP tool, or via REST with `metadata.type = "coherence_check"`.
```json
{ "error": "NOT_A_COHERENCE_ANCHOR", "message": "why_proof_id is not a coherence anchor. Create the WHY with the check_coherence MCP tool (or certify with metadata.type = \"coherence_check\") before linking." }
```

Also: `400 INVALID_REQUEST` (non-UUID ids, or identical ids), `404 WHY_PROOF_NOT_FOUND` / `404 WHAT_PROOF_NOT_FOUND` (proof missing or owned by another account).

**Check your history:** `GET https://provebeforeact.com/api/agents/{wallet}/coherence` — public, paginated (`limit`, `offset`). Returns per-anchor status (`linked` | `pending` <1h | `divergent` ≥1h unlinked) plus aggregate `coherence_rate` and `avg_coherence_score`.

### require_coherence_anchor — Policy gate for orchestrators

MCP tool implementing the **Coherence Artisan** pattern: before delegating or executing a sub-action, an orchestrator (or any supervising agent) verifies that a valid, unexpired WHY anchor exists for the intent. If none exists, execution is blocked until `check_coherence` is called. Read-only and **free** — it never consumes a credit.

**Tool schema:**
```json
{
  "name": "require_coherence_anchor",
  "arguments": {
    "intent_hash":     "string (optional) — the coherence_anchor hash returned by check_coherence (fastest path)",
    "intent":          "string (optional) — byte-identical to the check_coherence call",
    "context":         "string (optional) — byte-identical to the check_coherence call",
    "decision":        "string (optional) — byte-identical to the check_coherence call",
    "who":             "string (optional) — must match the check_coherence value",
    "max_age_minutes": "number (optional) — anchor validity window, default 120 (2h), max 1440"
  }
}
```

Pass either `intent_hash` alone, or all three of `intent` + `context` + `decision` (the anchor hash is recomputed deterministically, scoped to your account).

**Response (anchor valid):**
```json
{
  "allowed": true,
  "anchor_id": "<WHY proof_id>",
  "anchor_created_at": "ISO-8601",
  "expires_at": "ISO-8601",
  "already_linked": false,
  "verify_url": "https://provebeforeact.com/proof/<anchor_id>"
}
```

**Response (blocked):**
```json
{
  "allowed": false,
  "reason": "NO_ANCHOR | ANCHOR_EXPIRED",
  "required_action": "check_coherence"
}
```

**Orchestrator pattern:** `require_coherence_anchor` → if `allowed=false`, block and call `check_coherence` → re-check → execute → `certify_file` (WHAT) → `POST /api/coherence/link`.

### Divergence detection

A background scan (every 15 min) flags WHY anchors that stay unlinked past a TTL (default **2 hours**) as **divergent** — a declared intent with no proven result. Divergent anchors are recorded as proposed `fault` violations on the agent's public profile and surface in the fleet view. Linking a WHAT after the TTL improves the coherence score but does not clear the divergence flag.

### Fleet coherence — the Coherence Artisan view

Aggregate coherence across every agent in an organization (agents sharing a wallet-address prefix, public profiles only):

```bash
curl "https://provebeforeact.com/api/fleet/coherence?org=<wallet_prefix>"   # prefix: 6-62 lowercase alphanumeric chars
```

Returns per-agent stats (`total_anchors`, `linked_count`, `coherence_rate`, `divergent_count`, `avg_coherence_score`) plus a fleet-level score: `fleet_score = round(0.7 × coherence_rate + 0.3 × avg_coherence_score)`.

Human view: `https://provebeforeact.com/fleet`

### Coherence Layer page

Full documentation, code examples, and integration guide: `https://provebeforeact.com/coherence`

## Genesis

xproof's first certification (self-referential proof of concept):
- **Document**: XPROOF - Genesis.pdf
- **Hash**: `173200d6fa0d1577b456bb85dc505193e31dd8be5fc69bd4e461612a588427de`
- **Transaction**: `f376c0809d5c8fd91f854d39cf6f9f83ac3d80231477538a1b423db0537aad7e`
- **Date**: 2025-12-12T20:28:00Z

View: https://provebeforeact.com/genesis.proof.json

## Contact

Website: https://provebeforeact.com