NotaryOS

Cryptographic Verification

VerifyDocsPricingAbout
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(api_key="notary_live_...")
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(
    action="payment.processed",
    agent_id="billing-agent-01",
    payload={
        "amount": 49.99,
        "currency": "USD",
        "customer_id": "cust_abc123"
    }
)

print(receipt.hash)       # "sha256:a1b2c3d4..."
print(receipt.signature)  # "ed25519:SGVsbG8g..."
print(receipt.valid)      # True
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.hash)

assert result.valid           # True
print(result.signer_id)       # "notary-v1-ed25519"
print(result.chain_position)  # 42

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(api_key="notary_live_...")

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

# 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 NotaryClient

notary = NotaryClient()  # No API key needed for verification

# Get the receipt hash from OpenClaw's action log
receipt_hash = "sha256:a1b2c3d4e5f6..."

# Verify — works offline, no trust in OpenClaw required
result = notary.verify(receipt_hash)

print(result.valid)           # True — cryptographically verified
print(result.chain_position)  # 47 — position in the agent's action chain
print(result.checks)          # {"signature": "pass", "chain": "pass", "timestamp": "pass"}

# If someone tampered with the logs:
# result.valid = False
# result.checks["chain_linkage"] = "fail — hash mismatch"

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.

2-Line Integration

Call notary.wrap(agent) and every public method on your agent automatically issues a receipt.

agent.py
from notaryos import NotaryClient

notary = NotaryClient(api_key="notary_live_...")
notary.wrap(my_agent)  # Every public method now auto-receipts

my_agent.place_order("BTC", 10)    # Receipt issued automatically
my_agent.analyze(api_key="secret") # api_key redacted in receipt

Class Decorator

Use @receipted to auto-wrap every instance at construction time.

trading_bot.py
from notaryos import NotaryClient, receipted

notary = NotaryClient(api_key="notary_live_...")

@receipted(notary)
class TradingBot:
    def trade(self, symbol, amount):
        return execute_trade(symbol, amount)

bot = TradingBot()  # Auto-wrapped at __init__
bot.trade("ETH", 5) # Receipt issued automatically

Configuration

Control receipt mode, sampling rate, and secret redaction.

config.py
from notaryos import NotaryClient, AutoReceiptConfig

config = AutoReceiptConfig(
    mode="all",           # "all", "errors_only", or "sample"
    sample_rate=0.5,      # Sample 50% of calls (for "sample" mode)
    fire_and_forget=True, # Non-blocking (background thread)
    dry_run=False,        # Set True to log without issuing
    redact_secrets=True,  # Redact args matching secret patterns
)

notary = NotaryClient(api_key="notary_live_...")
notary.wrap(agent, config=config)

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+. Async-first with synchronous wrappers.

terminal
pip install notaryos
example.py
from notaryos import NotaryClient

notary = NotaryClient(api_key="notary_live_...")

# Seal an action
receipt = notary.seal(
    action="data.exported",
    agent_id="export-agent",
    payload={"rows": 15000, "format": "csv"}
)

# Verify by hash (no auth needed)
result = notary.verify(receipt.hash)
assert result.valid

# List recent receipts
history = notary.history(agent_id="export-agent", limit=10)
for r in history:
    print(f"{r.action} @ {r.signed_at} -> {r.hash[:16]}...")

TypeScript

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

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

const notary = new NotaryClient({ apiKey: 'notary_live_...' });

// Seal an action
const receipt = await notary.seal({
  action: 'email.sent',
  agentId: 'comms-agent',
  payload: {
    to: 'user@example.com',
    subject: 'Your order has shipped',
  },
});

// Verify anywhere (no API key required)
const result = await notary.verify(receipt.hash);
console.log(result.checks); // { signature: 'pass', ... }

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
DocsAPIPrivacyTerms
© 2026 NotaryOS. All rights reserved.