Prove Before Act Agent Context

Quick Start — 3 steps

# 1. Get an API key (10 free proofs); keep it secret.
curl -X POST https://provebeforeact.com/api/agent/register -H "Content-Type: application/json" -d '{"agent_name": "my-agent"}'

# 2–3. Hash a fresh per-run basis, submit it, and gate the action on a fresh GET.
import hashlib, json, time, uuid, requests
from urllib.parse import quote

BASE = "https://provebeforeact.com"
API_KEY = "pm_YOUR_KEY"

def prove_before_act(decision_basis, action_fn):
    # Unique random nonce is local and included in the hash, never metadata.
    basis = dict(decision_basis)
    basis["action_id"] = str(uuid.uuid4())
    expected_hash = hashlib.sha256(
        json.dumps(basis, sort_keys=True, ensure_ascii=False).encode()
    ).hexdigest()

    post = requests.post(
        f"{BASE}/api/proof",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "file_hash": expected_hash,
            "filename": "decision_basis.json",
            "metadata": {"who": "my-agent", "action_type": "trade_execution"},
        },
        timeout=10,
    )
    if post.status_code not in (200, 201):
        raise RuntimeError(f"Proof POST failed: HTTP {post.status_code}; action blocked")
    body = post.json()
    proof_id = body.get("proof_id") or body.get("existing_proof_id")
    if not proof_id:
        raise RuntimeError("Proof POST response has no proof_id; action blocked")
    # 201 creates a pending proof; 200 is a duplicate, also not confirmation.
    deadline = time.monotonic() + 12
    while time.monotonic() < deadline:
        check = requests.get(
            f"{BASE}/api/proof/{quote(proof_id, safe='')}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=5,
        )
        if check.status_code != 200:
            raise RuntimeError(f"Proof GET failed: HTTP {check.status_code}; action blocked")
        proof = check.json()
        if proof.get("fileHash") != expected_hash:
            raise RuntimeError("Proof hash mismatch; action blocked")
        if proof.get("blockchainStatus") == "failed":
            raise RuntimeError("Proof confirmation failed; action blocked")
        if proof.get("verified") is True and proof.get("blockchainStatus") == "confirmed":
            return action_fn()
        time.sleep(1)
    raise TimeoutError("Proof was not confirmed within 12 seconds; action blocked")

# Pass the operator-controlled action here. It runs only after the fresh GET gate.
result = prove_before_act(
    {"why": "RSI=38", "what": "BUY BTC 0.5"},
    lambda: execute_trade("BUY", "BTC", 0.5),
)

HTTP 201 means a new pending proof; HTTP 200 means a duplicate, also not confirmation. This example fails closed unless a fresh GET for that proof ID matches this run's hash and reports verified=true and blockchainStatus=confirmed. PBA records the commitment; it does not enforce runtime execution or prove that an off-chain action occurred. The operator must keep control of the action gate.

Going to production? — 4 useful patterns

• Batch anchoring — POST /api/batch, up to 50 files per call, 50× fewer requests than one-by-one
• Retry policy — exponential backoff (1s→2s→4s), treat 201 as a new pending proof and 200 as a duplicate pending proof; fail closed on 409 and respect Retry-After on 429
• Monitoring — alert if daily proof volume drops below expected minimum
• Operator-enforced policy: no proof = no action — your own agent/runtime must implement and enforce this gate; PBA does not block actions

# Record-only batch example — IDs do not authorize any action.
# High-stakes actions require a unique per-run action_id and a fresh GET gate.
curl -X POST https://provebeforeact.com/api/batch -H "Authorization: Bearer pm_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"certifications":[{"file_hash":"hash1","filename":"action1.json"},{"file_hash":"hash2","filename":"action2.json"}]}'
# → {"results":[{"proof_id":"prf_...","status":"pending"},...]}

Use-case patterns

• Trading agent (Finance · High-value decisions) — Anchor a declared BUY/SELL basis before execution and link a recorded result; the operator enforces any gate.
• Research agent (Content · Reports · Analysis) — Anchor a declared basis and report hash; readers can check the record, not the report's truth or source validity.
• Support agent (Customer service · Support) — Record a declared decision before responding; useful for review, not a dispute-proof or compliance guarantee.

For trading, publishing, or customer-support actions, wrap the action in the Quick Start prove_before_act callback. Give each invocation a new declared basis; the helper adds a cryptographically random local action_id before hashing. It calls the action only after the matching proof is freshly GET-verified as confirmed. The proof verifies a commitment, not a trade, report's truth, support outcome, or other off-chain event.

Proof record shape

This illustrative record is not a production statistic or evidence that an off-chain action occurred. A confirmed proof establishes the commitment hash, not the truth of its contents or execution of an action.

{
  "who": "your-agent-id",
  "why_hash": "<sha256 of locally held declared basis>",
  "what": "Action or output description",
  "confidence_score": 0.87,
  "reversibility_class": "costly",
  "proof_id": "<returned-proof-id>",
  "verify_url": "https://provebeforeact.com/proof/<returned-proof-id>"
}

For current proof status and agent metrics, use the public profile or the proof verification endpoint. View the reference agent profile →

x402 — No API key, fully autonomous

Any agent with a USDC wallet on Base (eip155:8453) can anchor proofs without any account:

POST https://provebeforeact.com/api/proof (no auth) → HTTP 402 {"payment": {"amount": "10000", "currency": "USDC", "network": "eip155:8453"}}
Resend + X-PAYMENT: <base64-signed-payment> → HTTP 201 new pending proof or HTTP 200 duplicate; neither is confirmation.

Compatible: Coinbase CDP, Conway Terminal, OpenClaw. No MultiversX wallet required on the agent side. Before a high-stakes action, use the fresh-GET gate from Quick Start with a per-run unique action hash; require matching fileHash, verified=true, and blockchainStatus=confirmed.

Core output: Prove Before Act

Reported commitment/result ordering plus available 4W record fields (WHO / WHY / WHAT / WHEN); timestamps alone do not establish off-chain execution or runtime enforcement.

• WHO — Which agent, model, or actor made this decision
• WHAT — A recorded action/result claim or artifact hash, not an independent witness by default
• WHEN — A recorded proof timestamp; check its source and applicable chain confirmation
• WHY — The declared decision basis hash, not private intention or internal chain-of-thought

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

Prove Before Act records WHAT, WHEN, and WHY. MX-8004 is an optional WHO integration: check /api/mx8004/status for live configuration and /api/mx8004/job/{jobId} for individual validation outcomes. Active configuration alone does not confirm that a job completed.

Prove Before Act records WHAT / WHEN / WHY. MX-8004 can add WHO when configured; each validation job must be checked separately for completion.

Coherence Layer — Prove Before Act

The Coherence Layer links a declared WHY (intent, context, decision) to a recorded WHAT (output hash) using check_coherence, certify_file, and POST /api/coherence/link. An unlinked WHY anchor becomes divergent after 1 hour — a declared intent with no linked WHAT record. Neither the link nor a proof independently witnesses arbitrary off-chain execution.

check_coherence — Anchor your WHY before acting

This MCP tool records a WHY commitment; its returned ID or status alone is not authorization to act. Before a high-stakes action, the operator must require a fresh GET matching the unique per-run hash with verified=true and blockchainStatus=confirmed (see the Quick Start gate), then enforce that policy. Link a later WHAT record via certify_file.

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.

Response fields: proof_id, coherence_anchor (SHA-256 of payload), timestamp, blockchain_status, verify_url, next_step.link_why_to_what — include proof_id in certify_file metadata as why_proof_id.

The full 4W Prove Before Act loop

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. Without the link call, your WHY anchor stays unlinked: it shows as divergent in your public coherence history after 1 h, and after the 2 h 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 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.

POST https://provebeforeact.com/api/coherence/link
Authorization: Bearer pm_YOUR_API_KEY
Content-Type: application/json

{ "why_proof_id": "<UUID from check_coherence>", "what_proof_id": "<UUID from certify_file>" }

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

Error cases: 409 ALREADY_LINKED — WHY is already linked to a different WHAT. 400 NOT_A_COHERENCE_ANCHOR — why_proof_id is a regular proof; create the WHY with check_coherence or metadata.type = "coherence_check".

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

require_coherence_anchor — Coherence Artisan policy gate

MCP tool for orchestrators: it reports whether a valid, unexpired WHY anchor exists for the intent. If none exists it returns allowed: false; the caller must enforce that result and block delegation or execution. The tool does not block runtime actions. Read-only and free — never consumes a credit.

Anchor valid: returns allowed: true, anchor_id, anchor_created_at, expires_at, already_linked, verify_url.

Blocked: returns allowed: false, reason: "NO_ANCHOR | ANCHOR_EXPIRED", required_action: "check_coherence".

Orchestrator pattern: require_coherence_anchor → if allowed=false, the caller blocks and calls check_coherence → re-check → for a high-stakes action, fresh-GET the unique per-run proof and require matching hash plus confirmed verification → the operator may execute → certify_file (WHAT) → POST /api/coherence/link. These tools report records/policy results; they do not enforce the action.

Divergence detection

A background scan (every 15 min) flags WHY anchors that stay unlinked past the 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. Two modes:

• GET https://provebeforeact.com/api/fleet/coherence?org=<wallet_prefix> — every public agent whose wallet shares the prefix (6–62 lowercase alphanumeric chars)
• GET https://provebeforeact.com/api/fleet/coherence?fleet=<slug> — the explicitly registered members of a named fleet

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

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

Key metadata fields

Framework Integrations

• LangChain — pip install prove-before-act → XProofTool() in agent tools list (xproof module name is a legacy compatibility alias)
• CrewAI — XProofTool as @tool, anchor before crew.kickoff()
• AutoGen — register_for_llm() decorator, anchor in pre-action hook
• LlamaIndex — FunctionTool.from_defaults(fn=xproof.anchor)
• OpenAI Agents SDK — function_tool decorator, Prove Before Act in run loop
• Vercel AI SDK — tool() wrapper, anchor in execute() before action
• MCP — POST https://provebeforeact.com/mcp · core tools: register_trial, certify_file, verify_proof, audit_agent_session, investigate_proof; call tools/list for the complete catalog
• Fetch.ai / uAgents — XProofuAgentMiddleware(agent, api_key="pm_...") — one-line integration, anchors WHY proof before and WHAT proof after every message handler. Full example: github.com/jasonxkensei/prove-before-act-examples/tree/main/fetchai

MCP endpoint

POST https://provebeforeact.com/mcp — JSON-RPC 2.0, Streamable HTTP transport.

Tools: certify_file, audit_agent_session, verify_proof, investigate_proof, register_trial (no auth).

Add to Claude/Cursor: {"mcpServers": {"prove-before-act": {"url": "https://provebeforeact.com/mcp", "headers": {"Authorization": "Bearer pm_YOUR_KEY"}}}}

OpenClaw / ClawHub installation: Prove Before Act is published on ClawHub. Install the verified skill with openclaw skills install @jasonxkensei/xproof.

Pricing

• Free trial: 10 proofs — no wallet, no card (POST /api/agent/register)
• Pay-per-use via x402: $0.01 / proof — USDC on Base, no account needed
• Live price: the values below are calculated from the current rate at /api/pricing; they are not fixed published prices.
• Prepaid packs — current flat $0.01/cert:
  • Starter: 100 certs / $1.00 ($0.01/cert)
  • Pro: 1,000 certs / $10.00 ($0.01/cert)
  • Business: 10,000 certs / $100.00 ($0.01/cert)
• Pack payment options: hosted Stripe Checkout (additional option, useful for non-crypto buyers including the Chinese market) or USDC on Base.
• Stripe flow: POST /api/credits/stripe/checkout → open checkout_url → GET /api/credits/stripe/status/{session_id}. Credits are granted only by the signed Stripe webhook.
• Pay-per-proof: x402 (USDC on Base, no account). ACP/EGLD remains available for agent commerce.

Get your API key — 3 ways

1. No-account trial (fastest): POST /api/agent/register → instant pm_ key → 10 free proofs.

2. MultiversX wallet (operator flow, most common): Connect your xPortal wallet on provebeforeact.com/settings → create a pm_ API key → share it with your agent. Your wallet identity is anchored on-chain; the key is scoped, revocable, and tied to your MultiversX address.

3. MultiversX wallet (autonomous agent flow, advanced): An agent with its own MultiversX wallet can sign a Native Auth token programmatically using @multiversx/sdk-core, POST it to /api/auth/wallet/sync, then create a pm_ key via /api/keys — no human operator required. Only relevant for agents that hold their own on-chain identity.

4. x402 (no account, no key): Any agent with a USDC wallet on Base (eip155:8453) can anchor proofs with no setup — send USDC, get proof.

Live production reference: Moltbook (xproof_agent_verify)

1,316 confirmed public proofs; confirmation rate 100.00% across 1,316 finalized public proofs (0 failed); current streak 6 weeks; trust score 10,049 (Verified). Data generated 2026-11-03T05:09:08.472Z.

Public profile: View live agent profile

Register now — 10 free certs, no wallet, no card

POST /api/agent/register → instant pm_ key → anchor your first proof in under 30 seconds.

• The Prove Before Act specification — design pattern, core invariant, 4W audit trail, and reference implementation
• REST API docs
• Machine-readable (.md) — optimized for LLM context windows
• MCP endpoint — certify_file, audit_agent_session, register_trial
• Agent trust leaderboard — live ranked agents
• skill.md — one-file integration guide for AI frameworks