merkleon-sdk 0.3.1

Cryptographic proof of every AI agent action — tamper-evident, externally verifiable

Merkleon Python SDK

Cryptographic proof of every AI agent action — tamper-evident, externally verifiable.

Drop this SDK into your agent and every LLM call, tool invocation, file operation, or network request is hashed (SHA-256), chained (Merkle), and signed (Ed25519). The result is a server-side audit trail that any third party can mathematically verify — no trust in Merkleon required.

Why

Logs aren't proof. A startup with s3://my-bucket/logs/ has nothing a regulator, lawyer, or post-incident investigator can rely on — they can be edited after the fact. Merkleon turns each event into a link in a hash chain anchored by per-tenant Ed25519 keys. Tampering is detectable down to the byte.

• ✅ Tamper-evident — break the chain, break the proof
• ✅ Externally verifiable — public verifier, no Merkleon trust needed
• ✅ Stable across redeploys — your signing identity survives
• ✅ 4 lines of code to instrument any agent

Install

pip install merkleon-sdk

Optional auto-instrumentation extras:

pip install "merkleon-sdk[langchain]"   # LangChain callback
pip install "merkleon-sdk[openai]"      # OpenAI client wrapper
pip install "merkleon-sdk[all]"

Quickstart

from merkleon import Merkleon

m = Merkleon(
    endpoint="https://api.merkleon.in",
    api_key="va_…",                  # Settings → API Keys → Generate
    agent_id="research-bot",
)

# Sign one action
result = m.prove(
    "gpt-4o called: summarize Q4 earnings",
    agent="research-bot",
)
print(result["event_id"], result["event_hash"])

The response includes the server-assigned event_id, the SHA-256 event_hash, the prev_hash that anchors this event to the chain tip, an Ed25519 signature, and any anomaly alerts the detection layer raised:

{
  "status": "ingested",
  "event_id": "evt_c2db625a1166429c",
  "event_hash": "c0664aba383cf8a8…",
  "prev_hash": "0000000000000000…",
  "signature": "5e2b9d7c…",
  "alerts": []
}

Get an API key

1. Sign up at merkleon.in
2. Settings → API Keys → Generate
3. Set in your environment:

export MERKLEON_API_KEY="va_…"

The SDK reads MERKLEON_API_KEY and MERKLEON_ENDPOINT from the environment, so most code only needs:

from merkleon import Merkleon
m = Merkleon(agent_id="research-bot")

Higher-level helpers

m.track_llm(model="gpt-4o", prompt="...", token_count=412, cost_usd=0.0021)
m.track_tool(tool="bash", args={"cmd": "ls /tmp"})
m.track_file_read(path="/etc/secrets.json")
m.track_network(host="api.openai.com", port=443)

Each one wraps prove() with the right event-type shape so you don't have to think about it.

Verifying a proof

Anyone — including you, your customer's auditor, or a regulator — can verify an event without trusting Merkleon's server:

curl "https://api.merkleon.in/api/v1/chain/integrity?agent_id=research-bot"
# → {"clean": true, "events_verified": 1247, "broken_at": null}

Or use merkleon.in/verify and paste an event_id.

What gets sent

Hashes, never raw content (unless you opt in). Default behaviour:

Field	Sent?
Prompt text	❌ Only its SHA-256 hash
Response text	❌ Only its SHA-256 hash
Tool arguments	Hashed when the tool is sensitive
File path	✅ As-is (PII scrubbed)
Token count, cost, model name	✅
Process name, cmdline	✅ (PII scrubbed)
Network destination host + port	✅

PII scrubbing is on by default. Disable with Merkleon(scrub_pii=False).

Async / batched mode

For high-throughput agents, batch events client-side and flush periodically:

m = Merkleon(async_mode=True, batch_size=20, flush_interval=2.0)
# prove() now returns immediately and pushes to an in-memory queue
# Background thread flushes every 2s or every 20 events
m.flush()  # explicit flush before shutdown

Pricing

Free tier covers small projects: 100K events / month, 7-day retention, 1 agent. Paid tiers add longer retention, witness cosigners, SIEM export, and SOC 2 evidence packs. See pricing.

Links

• 🌐 merkleon.in
• 📚 Documentation
• 📝 Blog
• 🐙 GitHub
• 🐍 PyPI: merkleon-sdk
• 📦 npm: merkleon-sdk (TypeScript SDK)

License

MIT — see LICENSE.