NotaryOS

Cryptographic Verification

VerifyDocsPricingAboutTrustExplorerPanopticonV2OSINT
NotaryOSdocs
HomeAboutPricingDocs
GitHubTry Demo
Developer Documentation

NotaryOS Documentation

Cryptographic receipts for AI agent actions. Issue, verify, and chain receipts in three lines of code.

GitHub RepositoryPricing Plans

Quickstart

Go from zero to a verified receipt in under 60 seconds.

1

Install the SDK

pip install notaryos
2

Initialize with your API key

Get your API key from the API Keys dashboard. Starter tier includes 100 receipts/month.

from notaryos import NotaryClient

notary = NotaryClient()  # works instantly, no API key needed
3

Issue a receipt (seal)

Call seal() whenever your agent performs an action. The receipt is Ed25519-signed, timestamped, and linked to the previous receipt in the agent's hash chain.

receipt = notary.seal("payment.processed", {
    "amount": 49.99,
    "currency": "USD",
    "customer_id": "cust_abc123"
})

print(receipt.receipt_hash)   # "a1b2c3d4..."
print(receipt.signature)      # "SGVsbG8g..."
print(receipt.chain_sequence) # 1
4

Verify a receipt

Verification is public. No API key required. Anyone with the receipt hash can confirm it is authentic, untampered, and correctly chained.

result = notary.verify(receipt)

assert result.valid           # True
print(result.signature_ok)    # True
print(result.structure_ok)    # True

You are set up.

Every receipt is now Ed25519-signed, hash-chained, and third-party verifiable. Explore the API reference below for advanced usage.

API Reference

Base URL: https://api.agenttownsquare.com

All authenticated endpoints require a Bearer token in the Authorization header. Verification endpoints are public and require no authentication.

MethodEndpointDescriptionAuth
POST/v1/notary/sealIssue a new cryptographic receipt
POST/v1/notary/verifyVerify a receipt by hash or full JSONPublic
GET/v1/notary/r/:hashPublic receipt lookup by hashPublic
GET/v1/notary/historyPaginated verification history
GET/v1/notary/statusService health and signer infoPublic

POST/v1/notary/seal

Creates a signed receipt for an agent action. Returns the receipt with its hash, signature, chain position, and timestamp.

Request Body

json
{
  "action": "payment.processed",
  "agent_id": "billing-agent-01",
  "payload": {
    "amount": 49.99,
    "currency": "USD",
    "customer_id": "cust_abc123"
  },
  "metadata": {
    "idempotency_key": "txn_20260212_001"
  }
}

Response (201 Created)

json
{
  "receipt_hash": "sha256:a1b2c3d4e5f6...",
  "signature": "ed25519:SGVsbG8gV29ybGQ...",
  "signer_id": "notary-v1-ed25519",
  "signed_at": "2026-02-12T10:30:00.000Z",
  "action": "payment.processed",
  "agent_id": "billing-agent-01",
  "chain": {
    "previous_hash": "sha256:f6e5d4c3b2a1...",
    "sequence_number": 42
  },
  "valid": true
}

POST/v1/notary/verify

Verify a receipt. Accepts either a receipt hash string or a full receipt JSON object. No authentication required.

Request Body

json
{
  "receipt_hash": "sha256:a1b2c3d4e5f6..."
}

Response (200 OK)

json
{
  "valid": true,
  "signer_id": "notary-v1-ed25519",
  "signed_at": "2026-02-12T10:30:00.000Z",
  "chain_position": 42,
  "chain_valid": true,
  "checks": {
    "signature": "pass",
    "timestamp": "pass",
    "chain_linkage": "pass",
    "format": "pass"
  }
}

GET/v1/notary/r/:hash

Public receipt lookup. Returns the full receipt for any valid hash. Use this to build shareable receipt verification links.

terminal
curl https://api.agenttownsquare.com/v1/notary/r/sha256:a1b2c3d4e5f6...

Authentication

Authenticated endpoints require an API key header: X-API-Key: notary_live_.... Generate keys from the API Keys page.

Counterfactual Receipts

Prove an agent could have acted but chose not to. This is essential for regulated industries where proof of restraint is as important as proof of action.

Three Cryptographic Proofs

Capability

Proves the agent had the permissions and resources required to perform the action.

Opportunity

Proves the action was available at the time. Timestamp, state context, and trigger conditions are recorded.

Decision

Records the agent's deliberate choice not to act, with the reasoning provided.

Seal Levels

Receipts can be sealed at different trust levels, each providing increasing assurance guarantees.

Self-Inked

The agent signs its own receipt. Suitable for internal audit trails where the agent is trusted.

Counter-Sealed

A second agent or service co-signs the receipt. Provides mutual attestation and is the default for production workflows.

Oracle-Bound

An external oracle (timestamp authority, blockchain anchor, or trusted third party) provides an independent attestation. Maximum assurance for compliance-critical actions.

Commit-Reveal Protocol

Counterfactual receipts use a two-phase commit-reveal protocol to prevent after-the-fact fabrication.

1

Commit Phase

The agent publishes a hash of its decision before the outcome is known. This locks in the decision without revealing it.

2

Reveal Phase

After the decision window closes, the agent reveals the original data. Anyone can verify the reveal matches the commitment hash.

counterfactual.py
# Phase 1: Commit the decision
commitment = notary.commit(
    action="trade.execute",
    agent_id="trading-bot-01",
    decision="decline",
    reason="Risk threshold exceeded",
    proofs={
        "capability": capability_proof,
        "opportunity": opportunity_proof,
        "decision": decision_proof,
    }
)

# Phase 2: Reveal after the window closes
receipt = notary.reveal(commitment.id)
print(receipt.counterfactual)  # True
print(receipt.proofs)          # All three proofs attached

Integrations

Add cryptographic accountability to your existing agent framework in minutes. NotaryOS works with any agent system that makes API calls.

🦞

OpenClawFeatured

145K+ GitHub stars · Autonomous AI agent framework

OpenClaw agents execute shell commands, manage files, send emails, and browse the web autonomously. NotaryOS adds the missing accountability layer—every action gets a cryptographic receipt that proves what happened, when, and in what order.

Audit every action

Tamper-proof logs for file changes, API calls, and shell commands

Chain integrity

Hash-linked receipts detect if any action is inserted or deleted

Security teams

Verify agent behavior without trusting OpenClaw's own logs

OpenClaw AgentSkill — 3 lines to integrate

skills/notary_seal.py
from notaryos import NotaryClient

notary = NotaryClient()  # works instantly, no API key needed

async def notary_seal(action: str, payload: dict) -> dict:
    """OpenClaw AgentSkill: Seal every agent action with a cryptographic receipt."""
    receipt = notary.seal(action, payload)
    return {"receipt_hash": receipt.receipt_hash, "signature": receipt.signature}

# Register as an OpenClaw skill
SKILL_NAME = "notary_seal"
SKILL_DESCRIPTION = "Create a tamper-proof receipt for any agent action"
SKILL_HANDLER = notary_seal

Verify what your OpenClaw agent did

verify_openclaw_actions.py
from notaryos import verify_receipt

# Verify any receipt — no API key needed
is_valid = verify_receipt(receipt_dict)  # True

# Or use the client for full details
from notaryos import NotaryClient
notary = NotaryClient()
result = notary.verify(receipt_dict)

print(result.valid)         # True — cryptographically verified
print(result.signature_ok)  # True — Ed25519 signature intact
print(result.structure_ok)  # True — receipt structure valid

# Look up by hash (public)
info = notary.lookup(receipt_hash)
print(info["found"])  # True

Why this matters

Security researchers have flagged OpenClaw's autonomous capabilities as high-risk. NotaryOS receipts give security teams independent, cryptographic proof of every action—without relying on the agent's own logs.

Works with any agent framework

LangChain / LangGraph

Add seal() as a tool in your agent's toolkit. Every chain step gets a receipt.

CrewAI

Wrap crew task callbacks with NotaryOS. Audit multi-agent crew workflows.

AutoGen

Seal conversation turns and function calls between AutoGen agents.

Custom A2A / MCP

Use the REST API or SDKs directly. 3 lines of code, any language.

Auto-Receipting

Wrap any agent so every public method call automatically produces a cryptographic receipt—zero changes to the agent class.

Receipt Chaining

Link receipts into a provenance DAG — proving action B was caused by action A.

agent.py
from notaryos import NotaryClient

notary = NotaryClient()  # works instantly, no API key needed

# Step 1: Read the data
r1 = notary.seal("file.read", {"file": "report.pdf"})

# Step 2: Chain the next action to step 1
r2 = notary.seal("summary.generated", {
    "source": "report.pdf",
    "summary_length": 500
}, previous_receipt_hash=r1.receipt_hash)

print(r2.chain_sequence)  # 2 — linked to r1

Counterfactual Receipts

Prove your agent chose not to act — cryptographic proof of restraint via commit-reveal protocol.

counterfactual.py
from notaryos import NotaryClient

notary = NotaryClient(api_key="notary_live_xxx")

# Phase 1: Commit (reasoning is hashed, not stored)
result = notary.commit_counterfactual(
    action_not_taken="financial.execute_trade",
    capability_proof={"permissions": ["trade.execute"]},
    opportunity_context={"ticker": "ACME", "price": 142.50},
    decision_reason="Risk score exceeds threshold",
)

# Phase 2: Reveal (after min delay — proves you committed before revealing)
reveal = notary.reveal_counterfactual(
    result["receipt_hash"],
    "Risk score exceeds threshold"
)
assert reveal["success"]

Error Handling

Typed exceptions for every failure mode — rate limits, auth, and validation.

error_handling.py
from notaryos import NotaryClient, AuthenticationError, RateLimitError, ValidationError

notary = NotaryClient()

try:
    receipt = notary.seal("action", {"key": "value"})
except RateLimitError as e:
    # Demo key: 10 req/min. Wait e.retry_after seconds
    pass
except AuthenticationError:
    # Invalid or expired API key
    pass
except ValidationError:
    # Bad request (missing action_type, etc.)
    pass

Features

Secret Redaction

Args named api_key, password, token, secret, credential, auth are automatically replaced with [REDACTED].

Chain Linking

Receipts reference the previous receipt hash for tamper-evident ordering of agent actions.

Async Support

Detects async methods and creates matching async wrappers automatically.

Error Capture

Failed calls produce receipts with status: "error" and error_type for full accountability.

Fire-and-Forget

Background daemon thread with bounded queue. Receipt issuance never blocks your agent.

Unwrap & Stats

notary.unwrap(agent) restores originals. notary.receipt_stats shows issued/failed/dropped counts.

SDKs

Official SDKs for Python, TypeScript, and Go. Zero external dependencies. Install and integrate in under a minute.

Python

Requires Python 3.8+. Zero dependencies — uses only stdlib.

terminal
pip install notaryos
example.py
from notaryos import NotaryClient, verify_receipt

notary = NotaryClient()  # works instantly, no API key needed

# Seal an action (3 lines)
receipt = notary.seal("data.exported", {
    "rows": 15000,
    "format": "csv",
    "agent": "export-agent"
})
print(receipt.receipt_hash)   # SHA-256 hash
print(receipt.signature)      # Ed25519 signature
print(receipt.chain_sequence) # position in chain

# Verify (with API key — full details)
result = notary.verify(receipt)
assert result.valid and result.signature_ok

# Verify (no API key — public, returns bool)
is_valid = verify_receipt(receipt.raw)  # True

# Look up by hash (public)
info = notary.lookup(receipt.receipt_hash)
print(info["found"])  # True

TypeScript

Works in Node.js 18+ and modern browsers. Ships with full type definitions.

terminal
npm install notaryos
example.ts
import { NotaryClient, verifyReceipt } from 'notaryos';

const notary = new NotaryClient();  // works instantly, no API key needed

// Seal an action (positional args)
const receipt = await notary.seal('email.sent', {
  to: 'user@example.com',
  subject: 'Your order has shipped',
  agent: 'comms-agent',
});
console.log(receipt.receipt_hash);   // SHA-256 hash
console.log(receipt.signature);      // Ed25519 signature
console.log(receipt.chain_sequence); // position in chain

// Object form also works
const receipt2 = await notary.seal({
  actionType: 'email.sent',
  payload: { to: 'user@example.com' },
});

// Verify (with API key — full details)
const result = await notary.verify(receipt);
console.log(result.valid);        // true
console.log(result.signature_ok); // true

// Verify (no API key — public, returns boolean)
const isValid = await verifyReceipt(receipt); // true

GoComing soon

Go SDK is on the roadmap. Zero-dependency, context-aware with built-in retries. Star the repo to get notified when it ships.

Self-Hosting

Run NotaryOS in your own infrastructure for full control, air-gapped environments, or data residency requirements.

Self-hosting is on the roadmap

We are working on a self-hosted Docker image for air-gapped environments and data residency requirements. Interested in early access? Contact us to discuss enterprise self-hosting.

Use Managed Service (Free Tier)

Ready to get started?

Create your free account and issue your first cryptographic receipt in under a minute. No credit card required.

Create Free AccountTry the Demo
HomeAboutPricingGitHub
NotaryOS
NotaryOS - Cryptographic Receipt Verification
DocsAPISecurityPrivacyTerms
© 2026 NotaryOS. All rights reserved.
NotaryOS protocol and counterfactual receipt system created by Harris Abbaali.