Documentation

Install

# TypeScript / JavaScript
npm install @proofledger/sdk

# Python
pip install proofledger

Create an API key in the dashboard under API Keys.

TypeScript quick start

import { ProofLedger } from "@proofledger/sdk";

ProofLedger.enable({
  apiKey: process.env.PROOFLEDGER_API_KEY,
  baseUrl: "https://proofledger.dev",
  projectId: "proj_...",
});

// One-shot
await ProofLedger.track({
  agentId: "support-agent",
  userId: "user_123",
  input: "User prompt",
  output: "Agent response",
  model: "gpt-4.1",
  provider: "openai",
});

// Wrap a unit of work as a fully-traced run
await ProofLedger.withRun(
  { agentId: "research-agent", model: "claude-4-opus", provider: "anthropic" },
  async (run) => {
    await run.recordToolCall({ toolName: "web_search", input: { q: "ai" }, output: { hits: 3 } });
    return await myAgent.run("Research this");
  }
);

const result = await ProofLedger.verifyRun(runId); // { valid, issues, eventCount }

Python quick start

from proofledger import enable, track, with_run, verify_run

enable(api_key="tl_live_...", base_url="https://proofledger.dev", project_id="proj_...")

track(agent_id="support-agent", input="User prompt", output="Agent response",
      model="gpt-4.1", provider="openai")

def work(run):
    run.record_tool_call(tool_name="web_search", input={"q": "ai"}, output={"hits": 3})
    return "done"

with_run({"agent_id": "research-agent", "model": "claude-4-opus"}, work)

Both SDKs produce byte-for-byte identical hash chains, so runs from either language verify the same way.

Framework adapters

One-line instrumentation for popular stacks — duck-typed, no extra dependencies.

import { wrapOpenAI, createLangChainHandler } from "@proofledger/sdk";

// OpenAI — every chat.completions.create is captured as a run
const openai = wrapOpenAI(new OpenAI(), { agentId: "support-agent" });

// LangChain.js — pass the callback handler
await chain.invoke(input, { callbacks: [createLangChainHandler({ agentId: "research" })] });

# Python — OpenAI
from proofledger import wrap_openai
openai = wrap_openai(OpenAI(), agent_id="support-agent")

Human-in-the-loop approvals

Gate a sensitive agent action on human sign-off in the dashboard's Approvals page.

// TypeScript — blocks until approved, throws if denied
await ProofLedger.requireApproval({
  agentId: "billing-agent",
  title: "Refund $500 to user_123",
  detail: "Customer requested a full refund.",
});

# Python
require_approval(agent_id="billing-agent", title="Refund $500 to user_123")

AI-to-AI signed messages

Give each agent an Ed25519 identity and send cryptographically signed messages — verified server-side and shown on the Agent network page.

import { ProofLedger, createAgentIdentity } from "@proofledger/sdk";

const id = createAgentIdentity();              // { publicKey, privateKey }
await ProofLedger.registerAgentIdentity("agent-a", id.publicKey);

const { verified } = await ProofLedger.sendAgentMessage({
  fromAgent: "agent-a",
  toAgent: "agent-b",
  content: { task: "summarize ticket #4821" },
  privateKey: id.privateKey,
});

REST API

Authenticate API-key endpoints with Authorization: Bearer <key>. Base URL: https://proofledger.dev.

curl -X POST https://proofledger.dev/api/proofledger/runs \
  -H "authorization: Bearer $PROOFLEDGER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"runId":"run_demo","projectId":"proj_...","agentId":"support-agent","status":"success"}'

Verifying the chain

Every event commits to its payload and the previous event's hash. Re-verify any run:

GET /api/proofledger/verify/:runId
→ { "verification": { "status": "verified", "valid": true, "eventCount": 7, "issues": [] } }

Export the full, re-verifiable audit trail from the Compliance page or GET /api/proofledger/export?format=json.