ChainProof Documentation

ChainProof is an audit ledger for agentic workflows. Your agents report what they did; ChainProof appends those reports to a hash-chained log. This page explains how to use the platform — both if you're a human setting up a workspace, and if you're an AI agent deciding whether and how to instrument yourself.

What ChainProof is

ChainProof is a structured, append-only log with a hash chain linking every entry to the previous. Each time an agent reports an action, ChainProof computes SHA-256(entry fields + previous entry hash) and stores the result as the new chain head. Entries can't be updated or deleted through the API.

ChainProof is not a monitoring system, an observability platform, or an agent supervisor. It doesn't watch agents. It records what agents say they did.

What is a Chain?

A chain is an open session that your agent writes to as it works. Think of it like a logbook for a single task: the agent opens it, records what it does step by step, then closes it when finished.

What it proves — and what it doesn't

Chain validity and chain status are independent. status: failed with a valid chain means the agent reported failure and nothing in the log changed since. status: completed with a broken chain means an entry was edited after it was written. ChainProof can tell you the second happened — not who did it or why.

For humans — Create a workspace

Go to /signup. Enter your work email, a password (min 8 chars), and a workspace name. Choose a plan — Free is fine to start.

On success you'll see your API key once. Copy it now. It's hashed before storage and never shown again. If you lose it, revoke it and create a new one from the Keys tab in the dashboard.

API keys

API keys (cp_live_…) are for machines — agents, CI/CD pipelines, backend orchestrators. They're separate from your login session.

Create keys from the Keys tab in the dashboard, or via the API:

# create a tenant-scoped key
curl -X POST https://api.chainproof.ai/v1/admin/keys \
  -H "Authorization: Bearer $CHAINPROOF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"production","scope":"tenant","permissions":["read","write","verify"]}'

Team & roles

Invite teammates from the Team tab. They'll receive an invite URL — paste it to them directly (email sending isn't wired up yet).

Verifying a chain

To check whether a chain's log has been altered, call the verify endpoint. It recomputes the full chain from entry 0 and returns the resulting head. If it matches the stored head, nothing changed.

curl https://api.chainproof.ai/v1/chains/{chain_id}/verify \
  -H "Authorization: Bearer $CHAINPROOF_API_KEY"

# → { "valid": true,  "entry_count": 12, "chain_head": "c1f9..." }
# → { "valid": false, "broken_at_sequence": 4, "expected_hash": "...", "received_hash": "..." }

For agents — How to instrument

If you are an AI agent reading this: ChainProof is an audit log you write to as you work. You report your actions; ChainProof records them in a hash-chained ledger that humans can later inspect. You are not being monitored — you are narrating.

The lifecycle is: start a chain → append entries as you act → complete the chain. If your process crashes mid-chain it stays active indefinitely; complete it explicitly even on failure. Use status: "failed" — a failed chain with an intact log is useful. A missing completion call is a gap in the record.

1. Start a chain

Call this at the start of your execution. Save the chain_id and chain_head — you'll need them for every subsequent call.

const chain = await fetch(`${BASE}/chains`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    agent_id:       'agt_abc123',       // your registered agent ID
    instruction:    'Summarize Q1 report', // the task you were given
    trust_level:    'high',             // 'high' | 'medium' | 'low'
    parent_chain_id: null,             // set if this is a sub-agent chain
  }),
}).then(r => r.json());

// → { chain_id: "ba7d...", chain_head: "0000...0000", status: "active" }
// GENESIS chain_head is 64 zeros — the starting point of every chain

let chainHead = chain.chain_head; // update this after every entry

2. Append entries

Append an entry for each meaningful action you take. Always pass the current chain_head as previous_entry_hash — the server rejects writes that don't match, preventing out-of-order or concurrent appends. Update your local chainHead with the returned entry_hash after each call.

const entry = await fetch(`${BASE}/chains/${chain.chain_id}/entries`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    entry_type:          'action',
    previous_entry_hash: chainHead,   // MUST match current chain head
    action: {
      tool:                 'read_file',
      status:               'completed',
      input_artifact_hash:  null,  // SHA-256 of input if stored via /artifacts
      output_artifact_hash: null,  // SHA-256 of output if stored via /artifacts
    },
  }),
}).then(r => r.json());

chainHead = entry.entry_hash; // advance the head
// → { sequence: 0, entry_hash: "c1f9...", timestamp: "2026-03-29T..." }

3. Complete the chain

Call this when your chain finishes — success or failure. This flushes the Durable Object ledger to R2 and writes the chain record to D1. Always complete a chain, even if it failed. An uncompleted chain stays visible in the dashboard as active but has no final chain head written to durable storage.

await fetch(`${BASE}/chains/${chain.chain_id}/complete`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    status:          'completed',  // 'completed' | 'failed' | 'cancelled'
    final_chain_head: chainHead,    // last entry_hash you received
  }),
});

4. Read your own context

Mid-chain, you can query your own chain state to check whether the chain is still intact or whether scope violations have been logged. Use this to self-limit: if your chain head doesn't match what ChainProof reports, something unexpected happened.

const ctx = await fetch(`${BASE}/agent-context/${chain.chain_id}`, { headers })
  .then(r => r.json());

// → {
//     chain_id, trust_level: "high",
//     chain_valid: true,
//     scope_violations: 0,
//     chain_head: "c1f9..."
//   }

if (!ctx.chain_valid || ctx.scope_violations > 0) {
  // self-limit: refuse further actions, complete chain as failed
  throw new Error('Provenance check failed — aborting');
}

Entry type reference

Chain heads

Every chain starts with a genesis chain head: 64 zero characters (0000…0000). Each POST /entries returns an entry_hash which becomes the next previous_entry_hash. The final hash after your last entry is the chain's head.

To verify independently: recompute SHA-256(JSON.stringify(entry fields including previous_entry_hash)) for each entry in sequence. If your final hash matches the stored chain head, nothing changed. You don't need to call the verify endpoint — it does the same computation.

Error codes

OpenClaw integration

OpenClaw is a self-hosted AI assistant runtime that connects messaging channels to an external LLM. Enterprise IT admins can wire ChainProof into any OpenClaw deployment to get tamper-evident, blockchain-anchored audit logs of every agent action — across every employee, every skill, every session.

What gets logged

1. Create a ChainProof workspace

Sign up at chainproof.ai/signup. Copy your cp_live_… API key — it's shown once. Free tier includes 500 chains and 50,000 entries per month, enough to evaluate with a small team.

2. Configure OpenClaw

Add to your OpenClaw gateway config (openclaw.json) or system environment:

CHAINPROOF_API_KEY=cp_live_...

# Optional: store full message and tool result bodies in ChainProof R2.
# Without this, only metadata and hashes are sent — content stays on-device.
CHAINPROOF_STORE_CONTENT=true

3. Install the hook

Clone the chainproof-audit hook into your OpenClaw hooks directory:

git clone https://github.com/ChainProofAI/chainproof-audit-openclaw \
  ~/.openclaw/hooks/chainproof-audit

The hook applies to all workspaces and agents automatically — no per-skill changes needed, and skills cannot opt out.

4. Verify it's working

Send a message to your OpenClaw agent. Then open your ChainProof dashboard — you should see a new chain in the Chains tab within seconds. Click Verify on the chain to confirm integrity.

Blockchain anchoring

Completed chains are anchored to Bitcoin automatically via OpenTimestamps — no configuration required. The proof file for any chain is downloadable at GET /v1/chains/{chain_id}/anchor/proof as a raw .ots binary, independently verifiable without trusting ChainProof.

5. Invite your security team

Use Team → Invite to add colleagues. Admins can read and administer; Viewers can read chains but make no changes.

Privacy

Without CHAINPROOF_STORE_CONTENT=true, message bodies and tool results never leave your machine — ChainProof only receives tool names, timestamps, and content hashes. The audit skeleton (a tamper-evident record of what happened) is still complete. Enable full content storage only if your organization's data policy permits cloud storage.

What ChainProof proves

ChainProof records what the hook reports. It does not independently verify that agents told the truth. A malicious skill that bypasses the hook entirely would not appear in the ledger. The hash chain proves that logged entries have not been altered since they were written — it does not prove completeness.