NotaryOS — Cryptographic Receipts for Agent Actions

Seal your agent's actions with Ed25519 signatures. Issue tamper-evident receipts, verify them publicly, and maintain an auditable chain of every decision.

License

BSL-1.1 (Business Source License). See https://github.com/hellothere012/notaryos/blob/main/LICENSE

Trust Statement

By using this skill, action metadata (action type, timestamps, and a SHA-256 hash of the payload) is sent to api.agenttownsquare.com via HTTPS. Raw payload retention depends on your tier — see the Data Flow section below. Verification is free and requires no account. Full privacy policy: https://notaryos.org/privacy

Data Flow

The SDK sends your payload to the NotaryOS API via HTTPS POST. The server hashes the payload with SHA-256, signs the hash with Ed25519, and returns a receipt.

Tier	Payload Transmitted	Raw Payload Retained	Hash Stored	Signature Stored
Demo (no key)	Yes	No	Yes	Yes
Free	Yes	Metadata only	Yes	Yes
Pro	Yes	Configurable	Yes	Yes
Enterprise	Yes	Zero retention	Yes	Yes

The included sanitize.py module strips fields matching known sensitive patterns before transmission. Use it before every seal() call when handling user data.

External Endpoints

URL	Method	Data Sent	Purpose
`api.agenttownsquare.com/v1/notary/issue`	POST	action_type, payload JSON	Issue signed receipt
`api.agenttownsquare.com/v1/notary/verify`	POST	receipt JSON	Verify signature
`api.agenttownsquare.com/v1/notary/status`	GET	None	Health check
`api.agenttownsquare.com/v1/notary/r/{hash}`	GET	None	Receipt lookup
`api.agenttownsquare.com/v1/notary/public-key`	GET	None	Ed25519 public key

No other endpoints are contacted. No telemetry, analytics, or tracking.

Setup

pip install notaryos

No API key required. The SDK auto-injects a free demo key (10 req/min) when NOTARY_API_KEY is not set. For production rates, get a key at https://notaryos.org/sign-up and set NOTARY_API_KEY in your environment or OpenClaw config.

from notaryos import NotaryClient

notary = NotaryClient()  # works immediately — uses demo key if NOTARY_API_KEY is not set

Seal an Action

from notaryos import NotaryClient
from sanitize import sanitize_payload

notary = NotaryClient()

receipt = notary.seal(
    "file.created",
    sanitize_payload({
        "path": "/src/main.py",
        "lines_added": 42,
        "branch": "feature/auth"
    })
)

print(receipt.receipt_hash)
print(receipt.signature)

What to Seal

Default (always safe)

Action Type	When to Seal
`file.created`	Created or modified a file
`file.deleted`	Deleted a file
`command.executed`	Ran a shell command
`config.changed`	Modified system configuration

Extended (sanitize payload first)

Action Type	When to Seal
`email.sent`	Sent an email (strip body, keep subject)
`api.called`	Made an external API call (strip auth headers)
`data.accessed`	Accessed sensitive data (log access, not content)
`message.sent`	Sent a message (strip body if private)

Always run sanitize_payload() on extended actions before sealing.

Payload Guidelines

Include: File paths, counts, timestamps, branch names, public identifiers, action summaries.

Exclude: Authentication credentials, financial numbers, government IDs, message bodies, file contents, health information. The sanitize_payload() helper handles this automatically.

Verify a Receipt

from notaryos import verify_receipt

is_valid = verify_receipt(receipt.to_dict())  # True or False, no auth needed

Lookup by Hash

notary = NotaryClient()
result = notary.lookup("e1d66b0bdf3f8a7e...")

if result["found"] and result["verification"]["valid"]:
    print("Receipt is authentic and untampered")

Counterfactual Receipts

Record when your agent chose NOT to act:

receipt = notary.seal("trade.declined", {
    "reason": "risk_threshold_exceeded",
    "action_considered": "trade.execute",
    "decision": "blocked"
})

Receipt Chaining

r1 = notary.seal("file.read", {"file": "report.pdf"})
r2 = notary.seal("summary.generated", {
    "source": "report.pdf",
    "length": 500
}, previous_receipt_hash=r1.receipt_hash)

Error Handling

from notaryos import AuthenticationError, RateLimitError, ValidationError

try:
    receipt = notary.seal("action", {"key": "value"})
except RateLimitError:
    pass  # demo: 10 req/min, upgrade at notaryos.org
except AuthenticationError:
    pass  # invalid key
except ValidationError:
    pass  # bad request

Dependencies

sanitize.py (included): Zero external dependencies — uses only Python standard library (typing). Pure function, no I/O, no network, no side effects.
notaryos SDK (installed via pip): Also uses only the Python standard library — zero third-party dependencies. Source: https://pypi.org/project/notaryos/ | GitHub: https://github.com/hellothere012/notaryos

Key Points

NOTARY_API_KEY is optional — a demo key is auto-injected when not set (10 req/min)
Set NOTARY_API_KEY for production rates (get a key at https://notaryos.org/sign-up)
Both sanitize.py and the notaryos SDK use only the Python standard library (zero third-party deps)
Payloads transmitted via HTTPS to api.agenttownsquare.com
Use sanitize_payload() to strip sensitive fields before sealing
Verification is free and public — no API key needed
Ed25519 signatures (same scheme as SSH and TLS)

notaryos

Installation