Skill: jasonxkensei/xproof (version 3.0.0)

--s--BCL25,BASE64 name: xproof version: 3.0.0 description: Proof and accountability layer for AI agents. Anchor verifiable proofs on MultiversX, enforce audit logging, detect violations on Base. REST API, MCP, x402. No proof = no action. homepage: https://xproof.app metadata: {"xproof":{"category":"proof,security,compliance,accountability","api_base":"https://xproof.app"}} --- # xProof -- Proof & Accountability Layer for AI Agents This skill enables your agent to **anchor verifiable proofs on the MultiversX blockchain**, **enforce pre-execution audit logging**, and **detect violations via Base** -- creating tamper-proof, publicly verifiable records of existence, authorship, timestamp, decision accountability, and trust. **Why anchor proofs?** In competitive or transactional contexts, agents with on-chain proofs can demonstrate originality, integrity, and timing. Agents without proofs cannot. Verifiable proof is a structural advantage. **Why audit?** Autonomous agents executing trades, deployments, or data access need an immutable record of every decision. The Agent Audit Log Standard enforces this: no proof = no execution. **Why violations?** Trust requires accountability. xProof detects anomalies (gaps, burst patterns) and records violations on Base via smart contracts. Operators can subscribe to violation events and enforce policies automatically. ## Pricing **All-time volume pricing** (global pool, not per-user): - **0 - 100k proofs**: $0.05 per proof - **100k – 1M proofs**: $0.025 per proof - **1M+ proofs**: $0.01 per proof ## Quick Install ### Security ### Configuration ### 2. The Proof Lifecycle

path: LICENSE
content: MIT License

Copyright (c) 2026 xKensei

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


path: README.md
content: # xProof OpenClaw Skill

Certify files on MultiversX blockchain via [xProof](https://xproof.app) — the on-chain notary for AI agents.

## Install

Give OpenClaw the URL to this repo and select the `xproof` skill:

```
https://github.com/jasonxkensei/xproof-openclaw-skill
```

## What It Does

- **Certify** any file by anchoring its SHA-256 hash on MultiversX blockchain
- **Verify** existing proofs with full blockchain details
- **Batch certify** up to 50 files in a single call
- Files never leave your machine — only the hash is sent

## Quick Start

```bash
export XPROOF_API_KEY=pm_your_key
./xproof/scripts/certify.sh path/to/file.pdf
```

## Structure

```
xproof/
├── SKILL.md              # Skill definition + instructions
├── references/
│   └── api-reference.md  # Full API documentation
└── scripts/
    └── certify.sh        # One-command certification
```

## Protocols

Supports x402 (HTTP-native payments), ACP, MCP, and MX-8004.

## Cost

$0.05 per certification.

## Links

- [xProof Platform](https://xproof.app)
- [GitHub Action](https://github.com/marketplace/actions/xproof-certify)
- [API Docs](https://xproof.app/docs)


path: xproof/SKILL-v3.0.0.md
content: ---
name: xproof
version: 3.0.0
description: Proof and accountability layer for AI agents. Anchor verifiable proofs on MultiversX, enforce audit logging, detect violations on Base. REST API, MCP, x402. No proof = no action.
homepage: https://xproof.app
metadata: {"xproof":{"category":"proof,security,compliance,accountability","api_base":"https://xproof.app"}}
---

# xProof -- Proof & Accountability Layer for AI Agents

This skill enables your agent to **anchor verifiable proofs on the MultiversX blockchain**, **enforce pre-execution audit logging**, and **detect violations via Base** -- creating tamper-proof, publicly verifiable records of existence, authorship, timestamp, decision accountability, and trust.

**Why anchor proofs?** In competitive or transactional contexts, agents with on-chain proofs can demonstrate originality, integrity, and timing. Agents without proofs cannot. Verifiable proof is a structural advantage.

**Why audit?** Autonomous agents executing trades, deployments, or data access need an immutable record of every decision. The Agent Audit Log Standard enforces this: no proof = no execution.

**Why violations?** Trust requires accountability. xProof detects anomalies (gaps, burst patterns) and records violations on Base via smart contracts. Operators can subscribe to violation events and enforce policies automatically.

## Pricing

**All-time volume pricing** (global pool, not per-user):
- **0–100k proofs**: $0.05 per proof
- **100k–1M proofs**: $0.025 per proof
- **1M+ proofs**: $0.01 per proof

## Quick Install

```bash
mkdir -p .agent/skills/xproof/references

# Core Skill
curl -sL https://raw.githubusercontent.com/jasonxkensei/xproof-openclaw-skill/main/xproof/SKILL.md \
  > .agent/skills/xproof/SKILL.md

# Reference Manuals
for f in certification x402 mcp; do
  curl -sL "https://raw.githubusercontent.com/jasonxkensei/xproof-openclaw-skill/main/xproof/references/${f}.md" \
    > ".agent/skills/xproof/references/${f}.md"
done
```

## Security

- **NEVER** commit API keys to a public repository.
- **ALWAYS** add `.env` to your `.gitignore`.
- API keys are prefixed `pm_` -- treat them like passwords.
- x402 mode requires no API key (payment replaces authentication).
- **NEVER send plaintext content to xproof.app** -- always hash locally first (`sha256sum`, `crypto.subtle.digest`, or equivalent). The only field xproof accepts is `file_hash` (64-char SHA-256 hex). No raw text, documents, or binary data should ever leave your environment.
- **x402 is opt-in and autonomous** -- once enabled, your agent can initiate USDC payments on Base without per-transaction confirmation. Configure a spending cap in your agent framework and require human approval above your threshold before enabling x402 in production.
- **`llms.txt` and `llms-full.txt` are static documentation references** -- load them once at install time for API reference, not at runtime on every call. Fetching them dynamically on each invocation creates an unnecessary runtime dependency on xproof.app availability and a potential prompt-injection surface if the file is ever compromised.

---

## Configuration

### Option A: API Key Authentication

```bash
# ---- xProof ---------------------------------------------------------------
XPROOF_API_KEY="pm_..."                          # Your API key (from xproof.app)
XPROOF_BASE_URL="https://xproof.app"             # Production endpoint
```

Get an API key at [xproof.app](https://xproof.app) (connect wallet, go to Settings > API Keys).

### Option B: x402 Payment Protocol (No Account Required)

No configuration needed. Pay in USDC on Base (eip155:8453) directly in the HTTP request. The 402 response header tells your agent exactly what to pay. Price decreases with all-time volume (see Pricing section).

> **WARNING -- autonomous payments:** x402 is an opt-in mode that enables your agent to initiate on-chain USDC transactions without per-transaction user confirmation. Before enabling x402 in production:
> - Set a **spending cap** in your agent framework (e.g. max $N/day or $N/session).
> - Require **human approval** for any single call that would exceed your risk threshold.
> - Note that `POST /api/batch` supports up to 50 items per call -- at $0.05 each, a single batch can reach $2.50.
> - Disable x402 entirely in environments where autonomous spending is not authorised.

---

## 1. Core Skills Catalog

### 1.1 Proof Anchoring (REST API)
[Full Reference](references/certification.md)

| Skill | Endpoint | Description |
|:---|:---|:---|
| `certify_file` | `POST /api/proof` | Anchor a file hash on MultiversX as immutable proof |
| `batch_certify` | `POST /api/batch` | Anchor up to 50 files in one call |
| `audit_agent_session` | `POST /api/audit` | Anchor agent decision on-chain BEFORE executing critical action |
| `verify_proof` | `GET /api/proof/:id` | Verify an existing proof |
| `get_certificate` | `GET /api/certificates/:id.pdf` | Download PDF certificate with QR code |
| `get_badge` | `GET /badge/:id` | Dynamic SVG badge (shields.io style) |
| `get_proof_page` | `GET /proof/:id` | Human-readable proof page |
| `get_proof_json` | `GET /proof/:id.json` | Structured proof document (JSON) |
| `get_audit_page` | `GET /audit/:id` | Human-readable audit log page |

### 1.2 Proof Anchoring (MCP -- JSON-RPC 2.0)
[Full Reference](references/mcp.md)

| Tool | Description |
|:---|:---|
| `certify_file` | Create blockchain proof -- SHA-256 hash, filename, optional author/webhook |
| `verify_proof` | Verify existing proof by UUID |
| `get_proof` | Retrieve proof in JSON or Markdown format |
| `discover_services` | List capabilities, pricing, and usage guidance |
| `audit_agent_session` | Anchor agent decision on-chain BEFORE executing critical action |

### 1.3 Payment (x402)
[Full Reference](references/x402.md)

x402 is not a separate skill -- it is a payment method. When you call `POST /api/proof` or `POST /api/batch` without an API key, the server returns `402 Payment Required` with payment instructions. Your agent pays in USDC on Base and retries with an `X-Payment` header.

---

## 9. Violations Layer (Base)

xProof monitors agent behavior and detects anomalies. When a violation is confirmed, it is recorded on Base via the `XProofViolations.sol` smart contract, impacting the agent's trust score.

### Violation Types

| Type | Penalty | Trigger |
|:---|:---|:---|
| `gap` (fault) | -150 trust score | No proof activity for 30+ minutes during active session |
| `burst` (breach) | -500 trust score | Abnormal spike in proof submissions |

Smart contracts: [XProofViolations.sol](https://github.com/jasonxkensei/xProof/blob/main/contracts/XProofViolations.sol) | [ViolationWatcher.sol](https://github.com/jasonxkensei/xProof/blob/main/contracts/ViolationWatcher.sol)

Docs: [https://xproof.app/docs/base-violations](https://xproof.app/docs/base-violations)

---

## 10. Agent Proof Standard

xProof implements the open Agent Proof Standard -- a composable, chain-agnostic format for agent accountability.

Full specification: [AGENT_PROOF_STANDARD.md](https://github.com/jasonxkensei/xProof/blob/main/AGENT_PROOF_STANDARD.md)

Standard API: `GET /api/standard` | `GET /api/standard/validate` (POST)

---

## 11. Discovery Endpoints

| Endpoint | Description |
|:---|:---|
| `GET /.well-known/agent.json` | Agent Protocol manifest |
| `GET /.well-known/mcp.json` | MCP server manifest |
| `GET /.well-known/agent-audit-schema.json` | Agent Audit Log canonical schema |
| `GET /ai-plugin.json` | OpenAI ChatGPT plugin manifest |
| `GET /llms.txt` | LLM-friendly summary |
| `GET /llms-full.txt` | Complete LLM reference |
| `POST /mcp` | MCP JSON-RPC 2.0 endpoint |
| `GET /mcp` | MCP capability discovery |
| `GET /api/standard` | Agent Proof Standard specification |

---

## 12. Command Cheatsheet

```bash
# Hash locally first -- the original content must never leave your environment.
# xproof only receives the SHA-256 hex hash, filename, and metadata you choose to share.
sha256sum myfile.pdf | awk '{print $1}'
# Then POST the hash to /api/proof

# Anchor via MCP
curl -X POST https://xproof.app/mcp \
  -H "Authorization: Bearer pm_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"certify_file","arguments":{"file_hash":"...","filename":"myfile.pdf"}}}'

# Verify a proof
curl https://xproof.app/api/proof/<proof_id>

# Get badge (embed in README)
![xProof](https://xproof.app/badge/<proof_id>)

# Batch anchor
curl -X POST https://xproof.app/api/batch \
  -H "Authorization: Bearer pm_..." \
  -d '{"files":[{"file_hash":"...","filename":"a.txt"},{"file_hash":"...","filename":"b.txt"}]}'

# Health check
curl https://xproof.app/api/acp/health
```


path: xproof/claw.json
content: {
  "name": "xproof",
  "version": "3.1.0",
  "description": "Proof and accountability layer for AI agents. Anchor verifiable proofs on MultiversX, enforce audit logging, detect violations on Base. All-time volume pricing: starts at $0.05.",
  "author": "jasonxkensei",
  "homepage": "https://xproof.app",
  "repository": "https://github.com/jasonxkensei/xproof-openclaw-skill",
  "tools": [
    {
      "name": "certify_file",
      "description": "Anchor a file hash on MultiversX as immutable proof. All-time volume pricing: $0.05\u2013$0.01 per proof."
    }
  ],
  "config": {
    "requiredEnv": [],
    "optionalEnv": [
      "XPROOF_API_KEY"
    ],
    "baseUrl": "https://xproof.app",
    "auth": {
      "methods": [
        "bearer",
        "x402"
      ],
      "bearerPrefix": "pm_",
      "x402": {
        "chain": "Base (eip155:8453)",
        "token": "USDC",
        "pricing": "all-time volume: $0.05 (0\u2013100k), $0.025 (100k\u20131M), $0.01 (1M+)"
      }
    }
  }
}

path: xproof/clawhub.json
content: {
  "name": "xProof",
  "tagline": "Proof and accountability layer for AI agents -- MultiversX anchoring + Base violations",
  "description": "xProof is a proof and accountability layer that lets AI agents anchor verifiable proofs on MultiversX and enforce trust through violation detection on Base. Agents submit proofs of what they saw, decided, and produced -- anchored on-chain with 6-second finality. The 4W framework (WHO/WHAT/WHEN/WHY) structures every proof. Violations (gaps, bursts) are detected and recorded on Base via smart contracts, impacting trust scores. Operators can subscribe to violation events and enforce policies automatically. Supports single file, batch (up to 50), x402 payment (USDC on Base, no account needed), MCP integration, and the open Agent Proof Standard for cross-platform composability.",
  "category": "utility",
  "tags": [
    "proof",
    "accountability",
    "blockchain",
    "multiversx",
    "base",
    "violations",
    "trust",
    "agent-reputation",
    "on-chain",
    "MCP",
    "x402",
    "4W-framework",
    "agent-proof-standard"
  ],
  "version": "3.1.0",
  "license": "MIT",
  "pricing": "paid",
  "pricing_details": "All-time volume pricing: $0.05 (0\u2013100k proofs), $0.025 (100k\u20131M), $0.01 (1M+). EGLD or USDC on Base (x402)",
  "support_url": "https://github.com/jasonxkensei/xproof-openclaw-skill/issues",
  "homepage": "https://xproof.app",
  "repository": "https://github.com/jasonxkensei/xproof-openclaw-skill",
  "documentation_url": "https://xproof.app/docs",
  "mcp_endpoint": "https://xproof.app/mcp"
}

path: xproof/references/api-reference.md
content: # xProof API Reference (Quick Index)

Complete OpenAPI 3.1 spec is available at: `GET https://xproof.app/api/acp/openapi.json`

## Onboarding (No Account)

| Method | Path | Auth | Purpose |
|:---|:---|:---|:---|
| `POST` | `/api/agent/register` | None | Get a `pm_` key + 10 free proofs |
| `GET`  | `/api/agent/status` | Bearer | Credits remaining, last proof, agent metadata |

## Certification

| Method | Path | Auth | Purpose |
|:---|:---|:---|:---|
| `POST` | `/api/proof` | Bearer or x402 | Anchor a single file hash on MultiversX |
| `POST` | `/api/batch` | Bearer or x402 | Anchor up to 50 files in one call |
| `POST` | `/api/audit` | Bearer | Anchor an agent decision (audit log standard) |

## Verification (Public)

| Method | Path | Purpose |
|:---|:---|:---|
| `GET` | `/api/proof/:id` | JSON document for a proof UUID |
| `GET` | `/api/proof/hash/:hash` | JSON document for a file hash |
| `GET` | `/proof/:id` | Human-readable proof page (HTML) |
| `GET` | `/proof/:id.json` | Same data as `/api/proof/:id` |
| `GET` | `/api/certificates/:id.pdf` | Downloadable PDF certificate with QR |
| `GET` | `/badge/:id` | SVG status badge (shields.io style) |
| `GET` | `/audit/:id` | Human-readable audit log page |

## Trust & Standards

| Method | Path | Purpose |
|:---|:---|:---|
| `GET` | `/api/standard` | Agent Proof Standard specification |
| `POST` | `/api/standard/validate` | Validate a proof document against the standard |
| `GET` | `/api/artifact/trust/:hash` | Aggregate trust score for an artifact |
| `GET` | `/api/v1/skills/xproof/file?path=...` | Read a published Clawhub skill file |

## MCP

| Method | Path | Purpose |
|:---|:---|:---|
| `POST` | `/mcp` | JSON-RPC 2.0 endpoint (requires `Accept: application/json, text/event-stream`) |
| `GET`  | `/mcp` | MCP capability discovery |

## Discovery

| Method | Path | Purpose |
|:---|:---|:---|
| `GET` | `/api/acp/openapi.json` | OpenAPI 3.1 spec (full REST surface) |
| `GET` | `/api/acp/health` | Health check |
| `GET` | `/.well-known/agent.json` | Agent Protocol manifest |
| `GET` | `/.well-known/mcp.json` | MCP server manifest |
| `GET` | `/.well-known/agent-audit-schema.json` | Audit log canonical schema |
| `GET` | `/ai-plugin.json` | OpenAI ChatGPT plugin manifest |
| `GET` | `/llms.txt` | LLM-friendly summary |
| `GET` | `/llms-full.txt` | Complete LLM reference |


path: xproof/references/certification.md
content: # Certification API

REST endpoints for registering an agent, creating blockchain certifications on MultiversX, and reading status.

## Bootstrap

### `POST /api/agent/register` -- Free Trial Registration (No Auth)

Get a `pm_` API key instantly with 10 free certifications. No wallet, no credit card, no signup form.

**Authentication:** None.

**Request:**

```json
{
  "agent_name": "my-agent",
  "webhook_url": "https://your-agent.com/hooks/xproof"
}
```

| Field | Type | Required | Description |
|:---|:---|:---|:---|
| `agent_name` | string | Yes | 2-128 chars. Used to deduplicate trial registrations per identity. |
| `webhook_url` | string | No | HTTPS callback for on-chain confirmation events. |

**Response (201 Created):**

```json
{
  "api_key": "pm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "agent_name": "my-agent",
  "trial": {
    "quota": 10,
    "used": 0,
    "remaining": 10
  },
  "endpoints": {
    "certify": "POST https://xproof.app/api/proof",
    "batch": "POST https://xproof.app/api/batch",
    "audit": "POST https://xproof.app/api/audit",
    "status": "GET https://xproof.app/api/agent/status",
    "verify": "GET https://xproof.app/api/proof/{proof_id}"
  },
  "quick_start": {
    "steps": [
      {"step": 1, "title": "Register", "done": true},
      {"step": 2, "title": "Certify your first file"},
      {"step": 3, "title": "Verify the proof publicly"},
      {"step": 4, "title": "Check remaining credits"}
    ]
  },
  "message": "Trial registered. 10 free proofs available. Treat your api_key as a password."
}
```

**Errors:**

| Code | Meaning |
|:---|:---|
| `400` | Missing or invalid `agent_name` |
| `409` | Agent name already has an active trial (returns existing `agent_id`, no new key) |
| `429` | Rate limited (max 5 registrations per IP per hour) |

---

### `GET /api/agent/status` -- Agent Status & Credits

Get the agent's current trial credits, last certified proof, and usage statistics.

**Authentication:** API Key (`Authorization: Bearer pm_...`).

**Response (200 OK):**

```json
{
  "agent_id": "uuid",
  "agent_name": "my-agent",
  "is_trial": true,
  "credits_remaining": 8,
  "credits": {
    "trial_quota": 10,
    "trial_used": 2,
    "total_remaining": 8
  },
  "last_proof": {
    "id": "proof-uuid",
    "filename": "report.pdf",
    "verify_url": "https://xproof.app/proof/proof-uuid",
    "transaction_hash": "abc123...",
    "created_at": "2026-05-02T11:00:00.000Z"
  },
  "proofs": {
    "total": 2,
    "last_proof": { "...": "same as top-level last_proof" }
  }
}
```

**Errors:**

| Code | Meaning |
|:---|:---|
| `401` | Missing or invalid API key |

---

## Certification

### `POST /api/proof` -- Certify a Single File

Creates an immutable certification on MultiversX mainnet.

**Authentication:** API Key (`Authorization: Bearer pm_...`) or x402 payment.

**Request:**

```json
{
  "file_hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
  "filename": "report.pdf",
  "author_name": "MyAgent",
  "webhook_url": "https://your-agent.com/hooks/xproof"
}
```

| Field | Type | Required | Description |
|:---|:---|:---|:---|
| `file_hash` | string | Yes | SHA-256 hash (64 hex characters) |
| `filename` | string | Yes | Original filename with extension |
| `author_name` | string | No | Default: "AI Agent" |
| `webhook_url` | string | No | HTTPS URL for on-chain confirmation callback |

**Response (201 Created):**

```json
{
  "proof_id": "uuid-v4",
  "status": "certified",
  "file_hash": "a1b2c3...",
  "filename": "report.pdf",
  "verify_url": "https://xproof.app/proof/uuid-v4",
  "certificate_url": "https://xproof.app/api/certificates/uuid-v4.pdf",
  "blockchain": {
    "network": "MultiversX",
    "transaction_hash": "abc123...",
    "explorer_url": "https://explorer.multiversx.com/transactions/abc123..."
  },
  "credits_remaining": 9,
  "timestamp": "2026-05-02T12:00:00.000Z"
}
```

---

### `POST /api/batch` -- Batch Certification (Up to 50 Files)

```json
{
  "files": [
    {"file_hash": "abc...", "filename": "model.bin"},
    {"file_hash": "def...", "filename": "training.csv"}
  ],
  "author_name": "MyAgent"
}
```

**Response (207 Multi-Status):** Per-file results with `proof_id` and `status` for each.

---

### `POST /api/audit` -- Audit Log Anchoring

See [SKILL.md Section 8](../SKILL.md#8-agent-audit-log-standard) for the full canonical schema and enforcement pattern.

---

## Verification (Public, No Auth)

### `GET /api/proof/:id` -- Lookup by Proof UUID

Returns the structured proof document. Public if the certification was created with `is_public=true` (default for trial users) or by the proof owner.

```bash
curl https://xproof.app/api/proof/<proof_id>
```

### `GET /api/proof/hash/:hash` -- Lookup by File Hash

```bash
curl https://xproof.app/api/proof/hash/<sha256_hex>
```

### `GET /proof/:id` -- Human-readable proof page

Returns a styled HTML page with QR code, blockchain explorer link, and download buttons.

### `GET /proof/:id.json` -- Same data as JSON

### `GET /api/certificates/:id.pdf` -- Downloadable PDF Certificate

Returns a downloadable PDF certificate with QR code. Public.

### `GET /badge/:id` -- Dynamic SVG Badge

Returns a shields.io-style SVG badge showing certification status:
- **Verified** (green) -- hash found on-chain
- **Pending** (yellow) -- awaiting confirmation
- **Not Found** (red) -- no matching hash

Embed in Markdown:

```markdown
![xProof Certified](https://xproof.app/badge/<proof_id>)
```

---

## Webhook Payload

When a certification is confirmed on-chain, xProof sends a POST to the `webhook_url`:

```json
{
  "event": "proof.confirmed",
  "proof_id": "uuid-v4",
  "file_hash": "a1b2c3...",
  "filename": "report.pdf",
  "blockchain": {
    "network": "MultiversX",
    "transaction_hash": "abc123...",
    "explorer_url": "https://explorer.multiversx.com/transactions/abc123..."
  },
  "timestamp": "2026-05-02T12:00:00.000Z"
}
```

**Security:** HMAC-SHA256 signature in `X-Webhook-Signature` header.
**Retry:** 3 attempts with exponential backoff.

## Error Codes

| Code | Meaning |
|:---|:---|
| `400` | Invalid request (missing/malformed `file_hash` or `filename`) |
| `401` | Missing or invalid API key |
| `402` | Payment required (x402 mode) |
| `403` | Trial quota exhausted -- top up via wallet or use x402 |
| `409` | File already certified (returns existing certification) |
| `429` | Rate limit exceeded |
| `500` | Internal server error |


path: xproof/references/mcp.md
content: # MCP Server

xProof exposes a Model Context Protocol (MCP) JSON-RPC 2.0 endpoint for AI agent integration.

## Endpoint

```
POST https://xproof.app/mcp
```

**Required headers on every call:**

```
Content-Type: application/json
Accept: application/json, text/event-stream
```

**Authentication:** API Key (`Authorization: Bearer pm_...`) -- except for `register_free_trial`, `verify_proof`, `get_proof`, `discover_services`, `check_attestations`, and `investigate_proof`, which are public.

## Bootstrap (No Account, No Wallet)

If your agent has no key yet, call `register_free_trial` first -- it's the only MCP tool that requires no authentication. It returns a `pm_` API key with 10 free certifications.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "register_free_trial",
    "arguments": {
      "agent_name": "my-agent"
    }
  }
}
```

**Response (excerpt):**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"api_key\":\"pm_xxxxx\",\"trial\":{\"quota\":10,\"used\":0,\"remaining\":10},\"agent_name\":\"my-agent\",\"endpoints\":{...}}"
    }]
  }
}
```

Store the `api_key` and use it as `Authorization: Bearer pm_xxxxx` for all subsequent authenticated calls.

## Available Tools

### `register_free_trial` (no auth)

Get a free `pm_` API key instantly. 10 free certifications, no wallet, no credit card.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `agent_name` | string | Yes | Agent identifier (2-128 chars, used to deduplicate trials) |

---

### `certify_file`

Create a blockchain certification for a file.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `file_hash` | string | Yes | SHA-256 hash (64 hex characters) |
| `filename` | string | Yes | Original filename with extension |
| `author_name` | string | No | Name of the certifier (default: "AI Agent") |
| `webhook_url` | string | No | HTTPS URL for on-chain confirmation callback |

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "certify_file",
    "arguments": {
      "file_hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
      "filename": "report.pdf",
      "author_name": "MyAgent"
    }
  }
}
```

**Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"proof_id\":\"uuid-v4\",\"status\":\"certified\",\"file_hash\":\"a1b2c3...\",\"filename\":\"report.pdf\",\"verify_url\":\"https://xproof.app/proof/uuid-v4\",\"certificate_url\":\"https://xproof.app/api/certificates/uuid-v4.pdf\",\"blockchain\":{\"network\":\"MultiversX\",\"transaction_hash\":\"abc123...\",\"explorer_url\":\"https://explorer.multiversx.com/transactions/abc123...\"},\"timestamp\":\"2026-02-19T12:00:00.000Z\"}"
    }]
  }
}
```

---

### `certify_with_confidence`

Certify a file along with a confidence score, model name, and reasoning trace -- used for AI-generated content where provenance must include the model's self-reported certainty.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `file_hash` | string | Yes | SHA-256 hash of the artifact (64 hex chars) |
| `filename` | string | Yes | Original filename |
| `confidence` | number | Yes | 0.0 to 1.0 -- model's self-reported confidence |
| `model_name` | string | Yes | e.g. `gpt-4o`, `claude-sonnet-4`, `grok-4` |
| `reasoning_hash` | string | No | SHA-256 of the reasoning trace (linked WHY proof) |
| `author_name` | string | No | Default: "AI Agent" |

---

### `verify_proof` (no auth)

Verify an existing certification by UUID.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `proof_id` | string | Yes | UUID of the certification to verify |

---

### `get_proof` (no auth)

Retrieve a proof in structured JSON or Markdown format.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `proof_id` | string | Yes | UUID of the certification |
| `format` | string | No | `json` (default) or `md` |

Use `md` format for LLM consumption -- produces human-readable Markdown with all proof details.

---

### `discover_services` (no auth)

List xProof capabilities, pricing, and usage guidance. No parameters required.

**Returns:** Service description, pricing tiers ($0.05 / $0.025 / $0.01 per proof depending on all-time volume), list of tools, certification triggers, batch API details, free trial details, and supported protocols.

---

### `audit_agent_session`

Anchor an agent's decision on-chain BEFORE executing a critical action. If the call fails or no `proof_id` is returned, the agent MUST block execution.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `agent_id` | string | Yes | Wallet, DID, or free identifier |
| `session_id` | string | Yes | UUID for the execution session |
| `action_type` | string | Yes | `trade` / `deploy` / `data_access` / `transfer` / `api_call` |
| `action_description` | string | Yes | Human-readable intent |
| `inputs_hash` | string | Yes | SHA-256 of canonical action inputs |
| `risk_level` | enum | Yes | `low` / `medium` / `high` / `critical` |
| `decision` | enum | Yes | `approved` / `rejected` / `deferred` |
| `risk_summary` | string | No | Explanation of risk factors |
| `context` | object | No | Free-form metadata (model, env, etc.) |

See [SKILL.md Section 8](../SKILL.md#8-agent-audit-log-standard) for the complete enforcement pattern.

---

### `check_attestations` (no auth)

Check domain-specific attestations for an agent wallet on Base.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `wallet_address` | string | Yes | EVM address on Base (0x...) |
| `domain` | string | No | Filter by domain (e.g. `kyc`, `code-review`, `compliance`) |

Returns the list of attestations issued by recognized issuers, with timestamps and trust weights.

---

### `investigate_proof` (no auth)

Reconstruct the full 4W audit trail for a contested agent action. Walks back from a single proof_id to surface the WHY (decision), WHAT (output), WHEN (timestamps), and WHO (agent identity), including any linked audit log and violation records.

**Parameters:**

| Parameter | Type | Required | Description |
|:---|:---|:---|:---|
| `proof_id` | string | Yes | UUID of the disputed proof or audit record |
| `depth` | integer | No | Trail depth (default 3) |

Use this when an agent's action is challenged -- the response is a structured timeline suitable for dispute resolution or regulatory review.

---

## Discovery

| Endpoint | Description |
|:---|:---|
| `GET /mcp` | MCP capability discovery (tool list) |
| `GET /.well-known/mcp.json` | MCP server manifest |

## LLM Prompt Engineering

When exposing xProof to an LLM, use:

> **Skill: Bootstrap (no account)**
> "If you have no XPROOF_API_KEY in env, call `register_free_trial` first with your agent name. Store the returned `api_key`. You get 10 free proofs."

> **Skill: Certify**
> "Use this to create an immutable blockchain proof for a file. Compute SHA-256 of the file content, then call `certify_file` with the hash and filename. Cost: trial-free or $0.05."

> **Skill: Audit before action**
> "Before any high-risk action (trade, deploy, transfer), call `audit_agent_session` with the action details. If no `proof_id` is returned, BLOCK the action."

> **Skill: Verify**
> "Use this to check if a file has been certified. Pass the proof UUID to `verify_proof`. Returns blockchain transaction, timestamp, and verification status."


path: xproof/references/x402.md
content: # x402 Payments

HTTP 402 Payment Required protocol for zero-account certification. Pay per request in USDC on Base -- no API key, no signup, no account needed.

## Payment Flow

1. Agent sends `POST /api/proof` (or `/api/batch`) with no Authorization header
2. xProof responds with `402 Payment Required` and a JSON body containing payment requirements
3. Agent parses the `accepts` array to extract: `scheme`, `price`, `network`, `payTo`
4. Agent pays in USDC on Base (eip155:8453) via the x402 facilitator
5. Agent retries the original request with the `X-Payment` header (base64-encoded JSON payment payload)
6. xProof verifies and settles the payment, then processes the certification

## 402 Response Body

```json
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "price": "$0.05",
      "network": "eip155:8453",
      "payTo": "0x...",
      "maxTimeoutSeconds": 60,
      "description": "xproof single file certification"
    }
  ],
  "resource": "https://xproof.app/api/proof",
  "description": "xproof single file certification",
  "mimeType": "application/json"
}
```

## X-Payment Header

After paying, the agent retries the request with the `X-Payment` header. The header value is a **base64-encoded JSON** payment payload that the x402 facilitator can verify and settle.

```
X-Payment: eyJwYXltZW50Li4uIjoiLi4uIn0=
```

## Pricing

| Endpoint | Price |
|:---|:---|
| `POST /api/proof` | $0.05 per certification |
| `POST /api/batch` | $0.05 per file in batch |

## Supported Endpoints

Both certification endpoints support x402:

- `POST /api/proof` -- single file certification
- `POST /api/batch` -- batch certification (up to 50 files)

## Example Flow

```bash
# Step 1: Send request without auth
curl -i -X POST https://xproof.app/api/proof \
  -H "Content-Type: application/json" \
  -d '{"file_hash":"abc123...64hex","filename":"output.pdf"}'

# Response: HTTP/1.1 402 Payment Required
# Body: {"x402Version":1,"accepts":[{"scheme":"exact","price":"$0.05","network":"eip155:8453","payTo":"0x..."}],...}

# Step 2: Pay USDC on Base via x402 facilitator, get payment payload

# Step 3: Retry with X-Payment header (base64-encoded payment payload)
curl -X POST https://xproof.app/api/proof \
  -H "Content-Type: application/json" \
  -H "X-Payment: eyJwYXltZW50Li4uIn0=" \
  -d '{"file_hash":"abc123...64hex","filename":"output.pdf"}'

# Response: 200 OK with certification data
```

## Why x402?

- **No account required** -- any agent can certify without signup
- **No API key management** -- payment replaces authentication
- **Composable** -- any x402-compatible agent (Conway, OpenClaw, custom) can use xProof
- **Standard protocol** -- follows the x402 HTTP payment specification
- **USDC on Base** -- stable currency, low fees, fast confirmation

## Conway / OpenClaw Compatibility

Any Conway automaton or OpenClaw agent with x402 support can certify via xProof without prior registration. The agent just needs:

1. A USDC balance on Base (eip155:8453)
2. The ability to parse x402 `accepts` requirements from the 402 response body
3. The ability to construct and send an `X-Payment` header with a valid payment payload

No MultiversX wallet is required on the agent side -- xProof handles the blockchain anchoring.


path: xproof/scripts/certify.sh
content: #!/usr/bin/env bash
set -euo pipefail

XPROOF_API_URL="${XPROOF_API_URL:-https://xproof.app}"

if [ -z "${XPROOF_API_KEY:-}" ]; then
  echo "Error: XPROOF_API_KEY is not set."
  echo "Get your API key at https://xproof.app (connect wallet > API Keys)"
  echo "Then: export XPROOF_API_KEY=pm_your_key"
  exit 1
fi

if [ $# -lt 1 ]; then
  echo "Usage: certify.sh <file> [author_name]"
  echo ""
  echo "Certify a file on MultiversX blockchain via xProof."
  echo "Computes SHA-256 locally (file never leaves your machine)."
  echo ""
  echo "Examples:"
  echo "  certify.sh report.pdf"
  echo "  certify.sh build.zip \"CI Bot\""
  exit 1
fi

FILE="$1"
AUTHOR="${2:-}"

if [ ! -f "$FILE" ]; then
  echo "Error: File not found: $FILE"
  exit 1
fi

FILE_HASH=$(sha256sum "$FILE" | awk '{print $1}')
FILE_NAME=$(basename "$FILE")

echo "Certifying: $FILE_NAME"
echo "SHA-256:    $FILE_HASH"
echo ""

PAYLOAD="{\"file_hash\": \"$FILE_HASH\", \"filename\": \"$FILE_NAME\""
if [ -n "$AUTHOR" ]; then
  PAYLOAD="$PAYLOAD, \"author_name\": \"$AUTHOR\""
fi
PAYLOAD="$PAYLOAD}"

RESPONSE=$(curl -s -w "\n%{http_code}" \
  -X POST "${XPROOF_API_URL}/api/proof" \
  -H "Authorization: Bearer $XPROOF_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD")

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | head -n -1)

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
  PROOF_ID=$(echo "$BODY" | jq -r '.proof_id // .id // empty')
  VERIFY_URL=$(echo "$BODY" | jq -r '.verify_url // empty')
  TX_HASH=$(echo "$BODY" | jq -r '.blockchain.transaction_hash // .tx_hash // empty')
  EXPLORER_URL=$(echo "$BODY" | jq -r '.blockchain.explorer_url // empty')

  echo "Certified!"
  echo ""
  echo "Proof ID:     $PROOF_ID"
  echo "Verify:       $VERIFY_URL"
  [ -n "$TX_HASH" ] && echo "TX Hash:      $TX_HASH"
  [ -n "$EXPLORER_URL" ] && echo "Explorer:     $EXPLORER_URL"
  echo "Badge:        ${XPROOF_API_URL}/badge/${PROOF_ID}"
else
  echo "Error (HTTP $HTTP_CODE): $BODY"
  exit 1
fi


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (HIGH)