# Prove Before Act

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

The canonical proof layer for AI agents. Immutable blockchain certification on MultiversX.

## About
Prove Before Act is the canonical proof-of-existence service for AI agents. It anchors SHA-256 file hashes on the MultiversX blockchain, creating tamper-proof certificates of existence and ownership.

**4W breakdown — optional WHO from MX-8004, WHAT/WHEN/WHY from Prove Before Act:**

| | Question | Provided by |
|:--|:--|:--|
| WHO | Which agent or actor made this decision? | MX-8004 — optional identity integration; inspect /api/mx8004/status before relying on it |
| WHAT | What output or action was certified? | Prove Before Act — SHA-256 hash of the output, anchored on MultiversX mainnet |
| WHEN | Immutable timestamp? | Prove Before Act — MultiversX block finality (~6 s); not a self-reported clock |
| WHY | 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 its live status is active; production currently reports `not_configured`.

**Agent reference:** `https://provebeforeact.com/agent-context` — dedicated document covering the 4W audit trail deep-dive, x402 payment walkthrough, retry policy, cost per 1000 anchors, privacy model, fleet monitoring, latency benchmarks, and framework integration examples.

## 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://provebeforeact.com/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://provebeforeact.com/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://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"}'
```

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

### POST /api/proof — Simplified Certification

Single-call endpoint for AI agents. No checkout flow needed.

**Request:**
```json
{
  "file_hash": "64-char SHA-256 hex string",
  "filename": "decision-record.json",
  "author_name": "AI Agent (optional)",
  "webhook_url": "https://your-agent.example.com/webhooks/prove-before-act (optional)"
}
```

**Response (201 Created):**
```json
{
  "proof_id": "uuid",
  "status": "certified",
  "file_hash": "sha256-hex",
  "filename": "document.pdf",
  "verify_url": "https://provebeforeact.com/proof/{id}",
  "certificate_url": "https://provebeforeact.com/api/certificates/{id}.pdf",
  "proof_json_url": "https://provebeforeact.com/proof/{id}.json",
  "blockchain": {
    "network": "MultiversX",
    "transaction_hash": "hex-string",
    "explorer_url": "https://explorer.multiversx.com/transactions/..."
  },
  "timestamp": "ISO 8601",
  "webhook_status": "pending | delivered | failed | not_requested | not_applicable",
  "message": "File certified on MultiversX blockchain."
}
```

### Webhook Notifications

Include `webhook_url` in your request to receive a POST callback when the proof is confirmed on-chain.

**Webhook payload:**
```json
{
  "event": "proof.certified",
  "proof_id": "uuid",
  "status": "certified",
  "file_hash": "sha256-hex",
  "filename": "document.pdf",
  "verify_url": "https://provebeforeact.com/proof/{id}",
  "certificate_url": "https://provebeforeact.com/api/certificates/{id}.pdf",
  "proof_json_url": "https://provebeforeact.com/proof/{id}.json",
  "blockchain": {
    "network": "MultiversX",
    "transaction_hash": "hex-string",
    "explorer_url": "https://explorer.multiversx.com/transactions/..."
  },
  "timestamp": "ISO 8601"
}
```

**Security:** Each webhook is signed with HMAC-SHA256. Verify using:
- Header: `X-ProveBeforeAct-Signature` (hex-encoded HMAC of the JSON body)
- Header: `X-ProveBeforeAct-Event` (always `proof.certified`)
- Header: `X-ProveBeforeAct-Delivery` (certification ID)
- Legacy aliases: `X-xProof-Signature`, `X-xProof-Event`, and `X-xProof-Delivery` are sent with identical values during migration.

**Retry policy:** Up to 3 attempts with exponential backoff (immediate, 10s, 20s). Status updates: pending → delivered or failed.

## Authentication
- API keys are prefixed with `pm_` (e.g. `pm_abc123...`)
- Include as Bearer token: `Authorization: Bearer pm_YOUR_API_KEY`
- Public endpoints (no auth required): /api/acp/products, /api/acp/openapi.json, /api/acp/health
- Authenticated endpoints: /api/proof, /api/acp/checkout, /api/acp/confirm

## Pricing
Flat $0.01 per certification — no tiers, no promo. Prepaid packs: 100/$1, 1,000/$10, 10,000/$100. Buy packs with Stripe Checkout or USDC on Base. Stripe is an additional option, especially useful for non-crypto buyers. Current pricing: https://provebeforeact.com/api/pricing

## Why certify?
Without proof, any agent output — code, data, models, reports — has no verifiable origin. Prove Before Act creates immutable, on-chain evidence of what was produced, by whom, and when. Certified agents can prove originality and integrity. Non-certified agents cannot.

## Documentation & Machine Interfaces
- [Prove Before Act specification](https://provebeforeact.com/standard) — The Prove Before Act specification — design pattern, core invariant, 4W audit trail
- [OpenAPI Specification](https://provebeforeact.com/api/acp/openapi.json)
- [API Guide](https://provebeforeact.com/learn/api.md)
- [Service Discovery](https://provebeforeact.com/api/acp/products)
- [Health Check](https://provebeforeact.com/api/acp/health)
- [MCP Server (JSON-RPC)](https://provebeforeact.com/mcp)
- [MCP Manifest](https://provebeforeact.com/.well-known/mcp.json)
- [OpenAI Plugin](https://provebeforeact.com/.well-known/ai-plugin.json)
 - [Full Specification](https://provebeforeact.com/.well-known/provebeforeact.md)

## Proof Object Schema (v2.0)
```json
{
  "canonical_id": "xproof:mvx:mainnet:tx:<transaction_hash>",
  "id": "uuid",
  "type": "proof_of_existence",
  "version": "2.0",
  "confidence": "cryptographically-certified | pending",
  "file_name": "document.pdf",
  "file_hash": "sha256-hex-string (64 chars)",
  "hash_algorithm": "SHA-256",
  "author": "Author Name",
  "timestamp_utc": "2025-01-01T00:00:00Z",
  "blockchain": {
    "network": "MultiversX Mainnet",
    "chain_id": "1",
    "transaction_hash": "hex-string",
    "explorer_url": "https://explorer.multiversx.com/transactions/..."
  },
  "verification": {
    "method": "SHA-256 hash comparison",
    "proof_url": "https://provebeforeact.com/proof/{id}",
    "instructions": ["Compute SHA-256 hash", "Compare with file_hash", "Verify on explorer"]
  },
  "metadata": {
    "file_type": "application/pdf",
    "file_size_bytes": 12345,
    "is_public": true
  }
}
```

### Canonical Identifier Format
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:{hash}` - On-chain transaction hash

Note: `canonical_id` is null when confidence is pending (not yet anchored). It becomes permanent once confirmed.

### Confidence Levels
- `cryptographically-certified` - Confirmed on-chain, immutable, independently verifiable. canonical_id is set.
- `pending` - Not yet anchored on blockchain. canonical_id is null.

## Proof Access Formats
- JSON: `https://provebeforeact.com/proof/{id}.json`
- Markdown: `https://provebeforeact.com/proof/{id}.md`

## ACP Endpoints

### GET /api/acp/products
Discover available certification products. No authentication required.
```bash
curl https://provebeforeact.com/api/acp/products
```

### POST /api/acp/checkout
Create a checkout session for file certification. Requires API key.
```bash
curl -X POST https://provebeforeact.com/api/acp/checkout \
  -H "Authorization: Bearer pm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pba-certification",
    "inputs": {
      "file_hash": "a1b2c3d4e5f6...",
      "filename": "document.pdf",
      "author_name": "AI Agent"
    },
    "payer_wallet": "erd1YOUR_PAYER_WALLET",
    "payer_wallet_signature": "YOUR_128_CHAR_HEX_ED25519_SIGNATURE"
  }'
```

Sign `pba-acp-checkout:pba-certification:<file_hash>:<payer_wallet>` with
the payer wallet's Ed25519 private key before submitting checkout.

### POST /api/acp/confirm
Confirm a transaction after signing on MultiversX. Requires API key.
```bash
curl -X POST https://provebeforeact.com/api/acp/confirm \
  -H "Authorization: Bearer pm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "uuid",
    "tx_hash": "multiversx-transaction-hash"
  }'
```

### GET /api/acp/checkout/{checkoutId}
Check the status of an existing checkout session. Requires API key.
```bash
curl https://provebeforeact.com/api/acp/checkout/{checkoutId} \
  -H "Authorization: Bearer pm_YOUR_API_KEY"
```

## Verification Flow
1. Compute the SHA-256 hash of the original file locally
2. Compare the computed hash with the `file_hash` stored in the proof
3. Verify the blockchain transaction on MultiversX explorer using the `transaction_hash`
4. Confirm the transaction data field contains the file hash
5. The timestamp proves the file existed at that point in time

## MCP Server (Model Context Protocol)

Prove Before Act exposes a native MCP server at `POST https://provebeforeact.com/mcp` using JSON-RPC 2.0 over Streamable HTTP.

**Protocol**: JSON-RPC 2.0 over Streamable HTTP (spec version 2025-03-26)
**Authentication**: Bearer token (`pm_` prefixed API keys) via Authorization header
**Session**: Stateless (no session management required)
**Critical**: every request must include `Accept: application/json, text/event-stream` — without it the server returns "Not Acceptable" and tools/list returns an empty list.

### Available Tools

| Tool | Auth required | Description |
|------|--------------|-------------|
| `register_trial` | No | **START HERE** — Get 10 free certifications instantly — returns a pm_ API key with no wallet or payment |
| `certify_file` | Yes | Certify a SHA-256 file hash on MultiversX blockchain (proof of existence, authorship, timestamp) |
| `certify_with_confidence` | Yes | Staged certification with confidence score and decision_id. Supports reversibility governance. |
| `verify_proof` | No | Verify any existing Prove Before Act certification by proof_id |
| `get_proof` | No | Retrieve a proof as JSON or Markdown |
| `discover_services` | No | List available services, pricing, and capabilities |
| `audit_agent_session` | Yes | Certify a full WHY + WHAT dual-proof for an agent decision. An operator-installed guard may use the resulting proof_id to decide whether to continue. |
| `check_attestations` | No | Return active domain-specific attestations for an agent wallet (trust bonus per issuer level) |
| `investigate_proof` | x402 or API key | Full 4W audit trail (WHO, WHAT, WHEN, WHY) for a contested agent action |
| `submit_outcome` | Yes | Record the actual outcome against a confidence-anchored decision (operator-only, once per proof) |
| `get_calibration` | No | Query an agent's calibration quality: mean gap, bias label, variance, per-decision time series |

### Confidence-Level Anchoring — certify_with_confidence

This is Prove Before Act's most advanced feature. It creates an on-chain audit trail of your decision process — not just what you decided, but how confident you were at each stage and why.

**Stages:** `initial` → `partial` → `pre-commitment` → `final`. All stages share a `decision_id` UUID.

**Governance rule:** If `reversibility_class` is `irreversible` and `confidence_level < 0.95`, Prove Before Act records a policy violation on-chain.

**Full workflow:**
1. Anchor at `initial` (confidence 0.6) with your first assessment hash
2. Anchor at `pre-commitment` (confidence 0.8) as evidence accumulates
3. Anchor at `final` (confidence 1.0) when you commit to the action
4. Execute the action
5. Call `submit_outcome` with the actual result
6. `get_calibration` will show your bias (overconfident / underconfident / calibrated) over time

```bash
# Stage 1 — initial assessment
curl -X POST https://provebeforeact.com/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-initial.json","decision_id":"<uuid>","confidence_level":0.6,"threshold_stage":"initial","reversibility_class":"irreversible","why":"<instruction-hash>","who":"<agent-id>"}}}'

# Stage 2 — final commitment
curl -X POST https://provebeforeact.com/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":2,"method":"tools/call","params":{"name":"certify_with_confidence","arguments":{"file_hash":"<sha256>","filename":"decision-final.json","decision_id":"<same-uuid>","confidence_level":0.95,"threshold_stage":"final","reversibility_class":"irreversible"}}}'

# After execution — record outcome
curl -X POST https://provebeforeact.com/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":3,"method":"tools/call","params":{"name":"submit_outcome","arguments":{"proof_id":"<proof-id-from-final-stage>","actual_confidence":0.9,"outcome_notes":"action succeeded"}}}'
```

### Available Resources
- `Prove Before Act://specification` - Full Prove Before Act specification
- `Prove Before Act://openapi` - OpenAPI 3.0 specification

### Connect to MCP Server

**Initialize:**
```bash
curl -X POST https://provebeforeact.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'
```

**Call a tool:**
```bash
curl -X POST https://provebeforeact.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pm_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"discover_services","arguments":{}}}'
```

**Certify a file via MCP:**
```bash
curl -X POST https://provebeforeact.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pm_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"certify_file","arguments":{"file_hash":"a1b2c3d4...64-char-sha256-hex","filename":"document.pdf"}}}'
```

### MCP Client Configuration (Claude Desktop, Cursor, etc.)
```json
{
  "mcpServers": {
    "prove-before-act": {
      "url": "https://provebeforeact.com/mcp",
      "headers": {
        "Authorization": "Bearer pm_YOUR_API_KEY"
      }
    }
  }
}
```

## x402 Payment Protocol (HTTP 402)

Prove Before Act supports the x402 payment protocol as an alternative to API key authentication. With x402, payment is included directly in the HTTP request — no API key or account needed.

### Supported Endpoints
- `POST https://provebeforeact.com/api/proof` — single file certification
- `POST https://provebeforeact.com/api/batch` — batch certification (up to 50 files)

### Pricing
- Flat $0.01 per certification in USDC — no tiers, no promo
- Prepaid packs: 100/$1, 1,000/$10, 10,000/$100 via Stripe Checkout or USDC on Base
- Stripe pack flow: POST /api/credits/stripe/checkout → open checkout_url → poll GET /api/credits/stripe/status/{session_id}; only the signed Stripe webhook grants credits
- Current pricing: https://provebeforeact.com/api/pricing
- Network: Base (eip155:8453) for mainnet, Base Sepolia (eip155:84532) for testnet

### How it works
1. Send a certification request without any auth header
2. Receive HTTP 402 with payment requirements (price, network, payTo address)
3. Sign the payment with your wallet (USDC on Base)
4. Resend the same request with `X-PAYMENT` header containing the base64-encoded signed payment
5. Receive 200 with the certification result

### Example
```bash
# Step 1: Send request without auth → get 402 with payment requirements
curl -X POST https://provebeforeact.com/api/proof \
  -H "Content-Type: application/json" \
  -d '{"file_hash": "a1b2c3d4...sha256", "filename": "document.pdf"}'

# Step 2: Sign the payment (done client-side with your wallet)

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

### 402 Response Format
```json
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "price": "$0.01",
    "network": "eip155:8453",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60,
    "description": "Prove Before Act single file certification"
  }],
  "resource": "https://provebeforeact.com/api/proof",
  "description": "Prove Before Act single file certification",
  "mimeType": "application/json"
}
```

### Notes
- x402 is an alternative to API key auth — both methods work for /api/proof and /api/batch
- When x402 is configured, requests without any auth return 402 (with payment requirements) instead of 401
- No account registration or API key needed — just sign and pay

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

## SDKs

### Python SDK
Install: `pip install prove-before-act`
PyPI: https://pypi.org/project/prove-before-act/
`xproof` is the legacy import/package name retained for compatibility; new installs use `pip install prove-before-act`.

```python
from xproof import XProofClient  # legacy module name retained by the canonical package

client = XProofClient(api_key="pm_YOUR_API_KEY")

# Certify a file
proof = client.certify_file("path/to/file.pdf")
print(proof.verify_url)           # https://provebeforeact.com/proof/{id}
print(proof.blockchain.tx_hash)   # MultiversX transaction hash

# Certify with confidence levels
from xproof import certify_with_confidence
proof = certify_with_confidence(
    api_key="pm_...",
    file_hash="<sha256>",
    decision_id="<uuid>",
    confidence_level=0.8,
    stage="pre-commitment",
    reversibility_class="irreversible"
)

# Batch certification
proofs = client.certify_batch(["file1.pdf", "file2.json"])

# Verify
result = client.verify_proof(proof_id="<uuid>")
```

Framework integrations: LangChain, CrewAI, LlamaIndex, AutoGen, OpenAI Agents SDK, Vercel AI.

### JavaScript / TypeScript SDK
Install: `npm install prove-before-act`
npm: https://www.npmjs.com/package/prove-before-act

```typescript
import { XProofClient } from 'prove-before-act';

const client = new XProofClient({ apiKey: "pm_YOUR_API_KEY" });

// Certify a file
const proof = await client.certifyFile("path/to/file.pdf");
console.log(proof.verifyUrl);

// Certify with confidence levels
const staged = await client.certifyWithConfidence({
  fileHash: "<sha256>",
  decisionId: "<uuid>",
  confidenceLevel: 0.8,
  stage: "pre-commitment",
  reversibilityClass: "irreversible",
});

// LangChain tool
import { XProofTool } from 'prove-before-act/vercel';
const tool = new XProofTool({ apiKey: "pm_..." });
```

Framework integrations: LangChain, CrewAI, LlamaIndex, AutoGen, OpenAI Agents SDK, Vercel AI.

## MX-8004 Integration (Trustless Agents Standard)

Prove Before Act supports MX-8004, but the production integration is currently `not_configured`. Check `/api/mx8004/status` before relying on MX-8004 identity, validation, reputation, or oracle behavior.

### Available only when MX-8004 is active
- **Identity Registry**: agent identity integration
- **Validation Registry**: job validation integration
- **Reputation Registry**: on-chain reputation integration

### Configured validation flow
When active, the integration can register eligible certification data in its configured validation flow. The live status response is authoritative for availability and resulting validation status.

### ERC-8004 Feedback System
When the integration is active, the Reputation Registry may expose configured feedback operations:
- **giveFeedbackSimple(job_id, agent_nonce, rating)** — On-chain cumulative moving average scoring
- **giveFeedback(agent_nonce, value, decimals, tag1, tag2, endpoint, uri, hash)** — Raw signal feedback (no on-chain scoring, off-chain aggregation expected)
- **revokeFeedback(agent_nonce, feedback_index)** — Revoke previously submitted feedback
- **readFeedback(agent_nonce, client, index)** — Read feedback data (view)

### Endpoints
- `GET https://provebeforeact.com/api/mx8004/status` — MX-8004 integration status, capabilities, and contract addresses
- `GET https://provebeforeact.com/api/agent/{nonce}/reputation` — Query agent reputation score and job history
- `GET https://provebeforeact.com/api/mx8004/job/{jobId}` — Query job data from the Validation Registry
- `GET https://provebeforeact.com/api/mx8004/validation/{requestHash}` — Query validation status
- `GET https://provebeforeact.com/api/mx8004/feedback/{agentNonce}/{clientAddress}/{index}` — Read ERC-8004 feedback

### Specification
- GitHub: https://github.com/sasurobert/mx-8004
- Spec: https://github.com/sasurobert/mx-8004/blob/master/docs/specification.md
- Explorer: https://agents.multiversx.com

## Genesis Proof
The first certification ever created on Prove Before Act:
- File: XPROOF - Genesis.pdf
- Hash: 173200d6fa0d1577b456bb85dc505193e31dd8be5fc69bd4e461612a588427de
- Transaction: f376c0809d5c8fd91f854d39cf6f9f83ac3d80231477538a1b423db0537aad7e
- Explorer: https://explorer.multiversx.com/transactions/f376c0809d5c8fd91f854d39cf6f9f83ac3d80231477538a1b423db0537aad7e
- View: https://provebeforeact.com/proof/genesis

## Agent Trust Leaderboard

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

### Trust Score Formula
`score = confirmed_certs × 10 + last_30d_certs × 5 + seniority_bonus + streak_bonus + attestation_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.
- **Attestation bonus**: weighted by issuer level (Newcomer +10, Active +25, Trusted +40, Verified +50). Top 3 attestations counted (max 150 pts). Requires issuer to have ≥ 3 confirmed on-chain certifications. Revoked or expired attestations do not count.

### Trust Levels
| Level | Score Range | Meaning |
|-------|-------------|---------|
| Newcomer | 0-99 | Just started certifying |
| Active | 100-299 | Regular certification activity |
| Trusted | 300-699 | Established track record |
| Verified | 700+ | Extensive, sustained certification history |

### Opt-in
Agents configure their public profile (name, category, description, website) via Settings or API, then toggle `is_public_profile` to appear on the leaderboard.

### Pages
- `/leaderboard` — Public, sortable table with search, category filter, "attested only" toggle, and sort by score/certs/streak/attestations
- `/agent/{wallet}` — Public agent profile with trust score, stats, streak, domain attestation badges, and recent certifications timeline
- `/attestation/{id}` — Public attestation detail: domain, standard, issuer, subject agent, timeline, trust impact

### Endpoints
- `GET https://provebeforeact.com/api/leaderboard` — Public. Returns top 50 agents with public profiles, sorted by trust score. Includes `activeAttestations` field per entry.
- `GET https://provebeforeact.com/api/agents/{wallet}` — Public. Agent profile with trust score, certifications, attestations, and timeline
- `GET https://provebeforeact.com/api/trust/{wallet}` — Public trust lookup: score, level, certifications count, attestation count. No profile data required
- `PATCH https://provebeforeact.com/api/user/agent-profile` — Auth required. Update agent public profile (name, category, description, website, is_public_profile)

### Trust Badge
Embed a dynamic trust badge in any README or documentation:
```
GET https://provebeforeact.com/badge/trust/{wallet}.svg
```
Returns a shields.io-style SVG badge showing trust level and score. When the agent has domain attestations, the badge text is updated to display "Level · N attested (score)" to signal credentialed status at a glance.
```
GET https://provebeforeact.com/badge/trust/{wallet}/markdown
```
Returns ready-to-embed markdown with the badge image and link to the agent's public profile.

## Domain-Specific Attestations

Third-party certifying bodies (MHRA, ISO, SOC2, FCA, etc.) issue on-chain-anchored attestations linked to agent wallets. This is a trust layer on top of the on-chain proof track record.

### Why attestations matter
An autonomous agent cannot self-declare regulatory compliance. With Prove Before Act attestations, a recognized certifying body issues a cryptographically-anchored statement — immutable, publicly verifiable, revocable. The trust bonus varies by issuer reputation: +10 pts (Newcomer issuer), +25 pts (Active issuer), +40 pts (Trusted issuer), +50 pts (Verified issuer). Maximum +150 pts from top 3 attestations. Issuers must have ≥ 3 confirmed on-chain certifications to issue.

### Attestation domains
| Domain | Examples |
|-----------|--------------------------------------|
| healthcare | MHRA, NICE, FDA, EMA, ICH, MDR |
| finance | FCA, SEC, ESMA, FINRA, MAS, MICA |
| legal | ISO 27001, GDPR, CCPA, SOC2 Type II |
| security | NIST, CIS Controls, OWASP, CVE |
| research | arXiv, peer review, data provenance |
| other | Any other regulatory standard |

### Issuance & revocation flow
1. Issuer authenticates with their MultiversX wallet (Native Auth)
2. `POST /api/attestation` — subject wallet, domain, standard (e.g., ISO-27001), title, optional description and expiry
3. Anti-self-attestation enforced. Duplicate check per (domain, standard, issuer) triplet.
4. Subject's trust score increases immediately. Badge updates within 5 minutes (cache TTL).
5. `DELETE /api/attestation/{id}` — issuer-only revocation. Trust score decreases immediately.

### Attestation API
| 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 (sets status to revoked) |
| GET | /api/my-attestations/issued | Wallet auth | List attestations I have issued |

### MCP Integration
`check_attestations(wallet)` — MCP tool callable without authentication. Returns:
- `attestation_count` — number of active attestations
- `trust_bonus` — computed bonus (0, 50, 100, or 150)
- `attestations[]` — array with id, domain, standard, title, issuer_name, issuer_wallet, expires_at, issued_at, attestation_url

## 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. Prove Before Act 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**: When the optional MX-8004 integration is active, agents can register on-chain identities and route certifications through its validation flow. Check /api/mx8004/status — production currently reports not_configured.
- **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

## Agent Audit Log Standard

Operators can use a certified proof in their own critical-action policy. Prove Before Act records certifications; it is not an automatic compliance gate.
Schema: /.well-known/agent-audit-schema.json
action_type: trade_execution | code_deploy | data_access | content_generation | api_call | other
risk_level: low | medium | high | critical

Example 1 — Trade execution:
  POST /api/audit  Authorization: Bearer pm_YOUR_API_KEY
  Body: { "agent_id":"trading-bot","action_type":"trade_execution","action_description":"Buy 0.5 ETH on Uniswap v3","inputs_hash":"<sha256>","risk_level":"high","decision":"approved","risk_summary":"Slippage < 0.5%, liquidity verified on 3 pools" }

Example 2 — Smart contract deployment (MultiversX / Base):
An operator can choose to require a proof before a mainnet deployment. The proof_id is an irrevocable record that the deployment was intentional and approved. The operator decides whether a missing proof triggers a retry, review, stop, or another response.
  POST /api/audit  Authorization: Bearer pm_YOUR_API_KEY
  Body: { "agent_id":"deploy-agent","action_type":"code_deploy","action_description":"Deploy TokenSwap v3 to MultiversX mainnet — replaces v2 at erd1qqqq...abc","inputs_hash":"<sha256-of-bytecode+args+network>","inputs_manifest":{"fields":["bytecode_hash","constructor_args","gas_limit","target_network","audit_report_hash","simulation_tx_hash"],"sources":["mvx_mainnet_gateway","audit_pipeline","simulation_vm"]},"risk_level":"critical","decision":"approved","risk_summary":"Bytecode matches audited commit. Simulation passed 10/10. Gas within 5% of v2 baseline.","context":{"network":"MultiversX mainnet","audit_by":"CertiK #CK-2026-0811"} }

Returns: { proof_id, audit_url, decision, risk_level, blockchain }

Operator-policy workflow templates (operators choose how to handle a missing 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)

## Live Proof

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