# Prove Before Act Specification v1.0

> Every file created without proof is a file anyone can claim. Prove Before Act fixes that.

## Purpose

Prove Before Act 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. Prove Before Act creates immutable, on-chain evidence of what was produced, by whom, and when.

## Service

- **Name**: Prove Before Act
- **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

## Founder and product identity

- **Founder**: Jason Petitfourg — AI Product Builder
- **Canonical product**: Prove Before Act
- **Product role**: Accountability pattern for autonomous agents — declare a decision basis (WHY) before acting, then prove WHAT happened. xProof is the reference implementation.
- **Founder page**: https://provebeforeact.com/founder
- **Public evidence**: https://provebeforeact.com/proof/f8c3b35d-6ee1-4f76-a92b-1532a008df7b
- **Compatibility note**: Historical `xproof` identifiers remain supported in packages, agent IDs, and protocol records where required for compatibility. They are not a separate public product brand.

## 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)

A Prove Before Act 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 (stable legacy wire identifier from the former xproof brand, kept so existing canonical IDs remain valid)
- `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 a Prove Before Act 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

Prove Before Act does not act as a trusted third party.
Trust is derived entirely from the MultiversX blockchain.
The proof is self-verifiable without relying on Prove Before Act 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 via POST); GET serves connection documentation for people, crawlers, and agent discovery

### Documentation
- `/learn/proof-of-existence.md` - What is proof of existence
- `/learn/verification.md` - How to verify proofs
- `/learn/api.md` - API documentation
- `/standard` - The Prove Before Act specification: design pattern, core invariant, 4W audit trail, threat model, four primitives, and reference implementation. Canonical definition of the pattern at provebeforeact.com/standard
- `/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). Cross-links to /standard for the full specification

## 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": "decision-record.json", "webhook_url": "https://your-agent.example.com/webhooks/prove-before-act"}'
```

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-ProveBeforeAct-Signature`). `X-xProof-Signature` remains an identical legacy alias. Retries up to 3 times with exponential backoff.

## Agent Commerce Protocol (ACP)

Prove Before Act 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. Sign pba-acp-checkout:pba-certification:<file_hash>:<payer_wallet>
# with the payer wallet's Ed25519 private key, then create a checkout.
curl -X POST https://provebeforeact.com/api/acp/checkout \
  -H "Authorization: Bearer pm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"pba-certification","inputs":{"file_hash":"sha256_hash_here","filename":"decision-record.json"},"payer_wallet":"erd1YOUR_PAYER_WALLET","payer_wallet_signature":"YOUR_128_CHAR_HEX_ED25519_SIGNATURE"}'

# 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 Prove Before Act

Use Prove Before Act 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 a declared decision basis before execution and outputs after for compliance

**Historical beta — xproof_agent_verify** (legacy agent identifier): a past end-to-end beta test exercised 6 API endpoints. Timings and leaderboard values from that run are historical snapshots, not current guarantees — read the live agent profile for current data. Live proof: `https://provebeforeact.com/proof/f8c3b35d-6ee1-4f76-a92b-1532a008df7b`. Full review: `https://www.moltbook.com/post/1d6cf96b-5046-4c63-9ae5-43f8809f4562`

## x402 Payment Protocol

Prove Before Act 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

Prove Before Act 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 Prove Before Act automatically** by searching for terms like:
- "proof of existence", "blockchain certification", "audit trail", "decision provenance", "agent accountability"

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

### How Prove Before Act appears in the Bazaar

Prove Before Act'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 Prove Before Act 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 50 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": "Declared justification for this action — never internal chain-of-thought",
      "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 Prove Before Act:

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

## 4W Responsibility Split: MX-8004 vs Prove Before Act

Prove Before Act records WHAT, WHEN, and WHY. MX-8004 support is optional: inspect `GET https://provebeforeact.com/api/mx8004/status` before relying on its identity or reputation data. The current production status is `not_configured`.

| | Question | Provided by |
|:--|:--|:--|
| **W**HO | Which agent or actor made this decision? | **MX-8004** — optional identity integration when live status is active |
| **W**HAT | What output or action was certified? | **Prove Before Act** — SHA-256 hash of the output, anchored on MultiversX mainnet |
| **W**HEN | Immutable timestamp? | **Prove Before Act** — MultiversX block finality (~6 s); not a self-reported clock |
| **W**HY | What declared decision basis supported the action? | **Prove Before Act** — `action_description`, `risk_level`, and `context` fields from `/api/audit` |

Prove Before Act records **WHAT / WHEN / WHY**. MX-8004 can add **WHO** only when active; do not assume it is configured.

> **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)

Prove Before Act supports an MX-8004 integration, but it is not active unless the status endpoint reports `status: "active"`. Production currently reports `status: "not_configured"`, so certifications are not currently registered in its validation flow.

- **Identity Registry**: Available when the integration is active
- **Validation Registry**: Available when the integration is active
- **Reputation Registry**: Available when the integration is active
- **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

Prove Before Act 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).

**Integration pattern**: An operator can configure its agent to certify a decision session before an action, then apply its own policy to a missing `proof_id`. Prove Before Act records and verifies certifications; it does not automatically block the agent's 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 are operator-policy templates — they can return or raise a signal when a `proof_id` is unavailable, and the operator decides whether the agent retries, queues review, stops, or proceeds:

| 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 Prove Before Act 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 Prove Before Act'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.
- **Prove Before Act 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,
  "pba_linked": true,
  "pba_wallet": "erd1...",
  "pba_certs_linked": 441,
  "pba_trust_score": 4760,
  "pba_trust_level": "Verified",
  "pba_violations": { "fault": 0, "breach": 0, "proposed": 0 },
  "convergence": {
    "sigil_anchors": "WHO — cryptographic identity continuity (Solana receipt chain + Persistence Score)",
    "pba_anchors": "WHAT/WHEN/WHY — decision provenance per action (MultiversX blockchain)",
    "combined_coverage": "full 4W stack: WHO (SIGIL) + WHAT + WHEN + WHY (Prove Before Act)",
    "integration_hint": "Certify with metadata.sigil_public_key = <your_sigil_key> to link SIGIL identity to Prove Before Act anchors"
  },
  "verify_urls": {
    "sigil_profile": "https://sigilprotocol.xyz/agent.html?key=...",
    "pba_leaderboard": "https://provebeforeact.com/leaderboard",
    "pba_profile": "https://provebeforeact.com/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 Prove Before Act. 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...",
  "pba_linked": true,
  "pba_wallet": "erd1...",
  "pba_certs_linked": 88,
  "pba_certs_confirmed_on_chain": 85,
  "pba_trust_score": 1200,
  "pba_trust_level": "Trusted",
  "pba_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://provebeforeact.com/api/proof",
    "profile": "https://provebeforeact.com/agent/erd1...",
    "trust_badge_svg": "https://provebeforeact.com/badge/trust/erd1....svg",
    "mcp": "https://provebeforeact.com/mcp"
  },
  "recommended_action": "continue",
  "schema_version": "1.0",
  "partner": "mx-moltbot-starter-kit"
}
```

#### ElizaOS (plugin-prove-before-act / elizaos-registry)

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

Bridges ElizaOS character identity (WHO layer) with Prove Before Act proof anchoring (WHAT/WHEN/WHY). The ElizaOS side = character UUID, runtime version, session IDs, action types. The Prove Before Act 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-prove-before-act):** 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
  },
  "prove-before-act": {
    "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",
    "pba_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 Prove Before Act proof anchoring (WHAT/WHEN/WHY on MultiversX). The xAI side = agent ID, model version, session IDs, action types. The Prove Before Act 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
  },
  "prove-before-act": {
    "wallet": "erd1...",
    "trust_score": 1350,
    "trust_level": "Trusted",
    "violations": { "fault": 0, "breach": 0 }
  },
  "convergence": {
    "xai_anchors": "WHO — Grok reasoning engine, model identity, session context",
    "pba_anchors": "WHAT/WHEN/WHY — decision provenance anchored on MultiversX before output",
    "combined_coverage": "full 4W stack: WHO (xAI/Grok) + WHAT + WHEN + WHY (Prove Before Act)"
  },
  "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 Prove Before Act 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",
  "pba_wallet": "erd1...",
  "pba_certs_linked": 3,
  "pba_certs_confirmed_on_chain": 3,
  "pba_trust_score": 1350,
  "pba_trust_level": "Trusted",
  "convergence": {
    "mpp_anchors": "HOW — payment execution via Stripe/Tempo settlement layer",
    "pba_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** (legacy agent identifier) — autonomous verification agent that beta-tested all 6 API endpoints in a past run. Its timings and leaderboard values are historical snapshots; query the live agent profile for current data.
- 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 Prove Before Act'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_score": 0.85,
  "coherence_score_percent": 85,
  "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:** the top-level `coherence_score` is a 0–1 ratio (`0.85` above); `coherence_score_percent` is its explicit 0–100 equivalent (`85`). The nested legacy `coherence_check.coherence_score` also remains 0–100. Scoring is 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: an orchestrator (or any supervising agent) can verify that a valid, unexpired WHY anchor exists for an intent before delegating or executing a sub-action. Operators decide how to handle a missing anchor (for example, proceed, retry, review, or stop). 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

Prove Before Act'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