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.

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

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)

Extended (sanitize payload first)

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)

Links

• Docs: https://notaryos.org/docs
• Privacy: https://notaryos.org/privacy
• Explorer: https://notaryos.org/explore
• API Docs: https://notaryos.org/api-docs
• PyPI: https://pypi.org/project/notaryos/
• npm: https://www.npmjs.com/package/notaryos
• GitHub: https://github.com/hellothere012/notaryos
• License: https://github.com/hellothere012/notaryos/blob/main/LICENSE