NotaryOS SDK for TypeScript

v2.2.0 — Cryptographic receipts for AI agent actions.

Issue, verify, and audit agent behavior with Ed25519 signatures. Zero dependencies — uses native fetch() and Web Crypto API. Works in Node 18+, Deno, Bun, and modern browsers.

Install

npm install notaryos

Quick Start — 3 Lines

import { NotaryClient } from 'notaryos';

const notary = new NotaryClient();  // works instantly, no signup needed
const receipt = await notary.seal('data_processing', { key: 'value' });

That's it. No API key needed to start — the SDK uses a free demo key automatically (10 req/min). For production, sign up at notaryos.org and pass your own key:

const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });  // unlimited

What You Get

Every receipt includes:

• Ed25519 signature — tamper-evident proof
• Merkle chain linking — ordered history via previous_receipt_hash
• Receipt hash — SHA-256 for public lookup
• Verify URL — anyone can verify without an API key

Examples

Seal an Action

import { NotaryClient } from 'notaryos';

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

// Positional arguments (recommended)
const receipt = await notary.seal('financial.transfer', {
  from: 'billing-agent',
  to: 'ledger-agent',
  amount: 150.00,
  currency: 'USD',
});

// Object form (also works)
const receipt2 = await notary.seal({
  actionType: 'financial.transfer',
  payload: { amount: 150.00, currency: 'USD' },
});

console.log(receipt.receipt_id);     // receipt_abc123...
console.log(receipt.receipt_hash);   // sha256 hex
console.log(receipt.signature);      // Ed25519 signature
console.log(receipt.chain_sequence); // position in chain

Verify a Receipt

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

// Without API key (public, returns boolean)
import { verifyReceipt } from 'notaryos';
const isValid = await verifyReceipt(receiptJson); // true

Compute Hashes (Client-Side)

import { computeHash } from 'notaryos';

const hash = await computeHash({ key: 'value' });
// Matches server-side SHA-256 computation

Full API Reference

NotaryClient

const notary = new NotaryClient({
  apiKey: 'notary_live_xxx',     // Required
  baseUrl: 'https://...',        // Default: https://api.agenttownsquare.com
  timeout: 30_000,               // Default: 30s
  maxRetries: 2,                 // Default: 2
});

| Method | Auth | Description | |--------|------|-------------| | seal(actionType, payload, options?) | API Key | Issue a signed receipt (alias for issue) | | seal({ actionType, payload, ... }) | API Key | Object-form issue | | issue(actionType, payload, options?) | API Key | Issue a signed receipt | | issue({ actionType, payload, ... }) | API Key | Object-form issue | | verify(receipt) | API Key | Verify a receipt's signature and integrity | | verifyById(receiptId) | API Key | Verify by receipt ID (server-side lookup) | | status() | API Key | Service health check | | publicKey() | API Key | Get Ed25519 public key for offline verification | | me() | API Key | Get authenticated agent info (id, tier, scopes) |

Standalone Functions

| Function | Auth | Description | |----------|------|-------------| | verifyReceipt(receipt, baseUrl?) | Public | Quick verification, returns boolean | | computeHash(payload) | None | SHA-256 hash matching server computation |

Types

interface Receipt {
  receipt_id: string;
  timestamp: string;
  agent_id: string;
  action_type: string;
  payload_hash: string;
  signature: string;
  signature_type: string;
  key_id: string;
  chain_sequence?: number;
  previous_receipt_hash?: string;
  receipt_hash?: string;
  verify_url?: string;
}

interface VerificationResult {
  valid: boolean;
  signature_ok: boolean;
  structure_ok: boolean;
  chain_ok?: boolean;
  reason: string;
  details: Record<string, unknown>;
}

Error Handling

import { NotaryClient, AuthenticationError, RateLimitError, ValidationError } from 'notaryos';

try {
  const receipt = await notary.seal('action', { key: 'value' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid or expired API key (401)
  } else if (err instanceof RateLimitError) {
    // Too many requests — wait err.retryAfter seconds (429)
  } else if (err instanceof ValidationError) {
    // Request validation failed — check err.details (422)
  }
}

Works With Any AI Stack

NotaryOS is LLM-agnostic. It seals actions, not model calls:

// Your custom LLM — any model, any provider
const result = await myCustomLLM.generate('Analyze this document');

// Seal the proof
const receipt = await notary.seal('llm.inference', {
  model: 'my-custom-llm-v3',
  outputHash: await computeHash(result),
});

Get an API Key

1. Sign up at notaryos.org
2. Generate an API key from the dashboard
3. Keys start with notary_live_ (production) or notary_test_ (sandbox)

Links

• NotaryOS Documentation
• API Reference
• GitHub

License

BSL 1.1 (Apache 2.0 after 2029-02-25)