Quick Start

This guide walks you through creating, signing, and verifying an Agent Receipt using either the TypeScript or Python SDK.

In-process API — standalone and testing use

The examples below use the direct SDK signing API, where the calling process holds the private key. This is the legacy in-process pattern that ADR-0010 deprecates in favour of the agent-receipts-daemon. For production deployments, the daemon owns the key and emitters send events over a socket — see Daemon Setup.

TypeScript

1. Install

npm install @agnt-rcpt/sdk-ts

2. Create and sign a receipt

import {
  createReceipt,
  generateKeyPair,
  signReceipt,
  hashReceipt,
} from "@agnt-rcpt/sdk-ts";

const keys = generateKeyPair();

const unsigned = createReceipt({
  issuer: { id: "did:agent:my-agent" },
  principal: { id: "did:user:alice" },
  action: {
    type: "filesystem.file.read",
    risk_level: "low",
    target: { system: "local", resource: "/docs/report.md" },
  },
  outcome: { status: "success" },
  chain: {
    sequence: 1,
    previous_receipt_hash: null,
    chain_id: "chain_session-1",
  },
});

const receipt = signReceipt(unsigned, keys.privateKey, "did:agent:my-agent#key-1");
const hash = hashReceipt(receipt);

console.log(receipt.id);  // urn:receipt:<uuid>
console.log(hash);        // sha256:<hex>

3. Store and query

import { openStore } from "@agnt-rcpt/sdk-ts";

const store = openStore("receipts.db");
store.insert(receipt, hash);

const chain = store.getChain("chain_session-1");
console.log(`Chain has ${chain.length} receipt(s)`);

store.close();

4. Verify a chain

import { verifyChain } from "@agnt-rcpt/sdk-ts";

const result = verifyChain(chain, keys.publicKey);
console.log(result.valid);   // true
console.log(result.length);  // number of receipts verified

Python

1. Install

pip install agent-receipts

2. Create and sign a receipt

from agent_receipts import (
    CreateReceiptInput,
    create_receipt,
    generate_key_pair,
    hash_receipt,
    sign_receipt,
)

keys = generate_key_pair()

unsigned = create_receipt(
    CreateReceiptInput(
        issuer={"id": "did:agent:my-agent"},
        principal={"id": "did:user:alice"},
        action={
            "type": "filesystem.file.read",
            "risk_level": "low",
            "target": {"system": "local", "resource": "/docs/report.md"},
        },
        outcome={"status": "success"},
        chain={
            "sequence": 1,
            "previous_receipt_hash": None,
            "chain_id": "chain_session-1",
        },
    )
)

receipt = sign_receipt(unsigned, keys.private_key, "did:agent:my-agent#key-1")
receipt_hash = hash_receipt(receipt)

3. Verify a chain

from agent_receipts import verify_chain

receipts = [receipt]  # or load from storage
result = verify_chain(receipts, keys.public_key)
print(result.valid)   # True
print(result.length)  # number of receipts verified

Next steps

• Read the Introduction for background on the protocol
• See the Agent Receipt Schema for the full receipt structure
• Explore the Action Taxonomy to understand action types and risk levels
• Set up agent-receipts-hook to capture native tool calls — see Hook: Claude Code