@provenonce/sdk

Cryptographic identity and accountability SDK for AI agents. Chain-agnostic (Solana + Ethereum).

Install

npm install @provenonce/sdk

Registration

Before using the SDK, register your agent to get an API key:

import { register } from '@provenonce/sdk';

// No-wallet registration (default — identity only)
const creds = await register('my-agent-v1', {
  registryUrl: 'https://provenonce.io',
  registrationSecret: process.env.REGISTRATION_SECRET, // required in production
});

console.log(creds.hash);    // unique agent identity
console.log(creds.api_key); // use this for BeatAgent
console.log(creds.secret);  // save — shown only once

// Solana self-custody wallet (opt-in)
const withWallet = await register('my-org', {
  registryUrl: 'https://provenonce.io',
  walletModel: 'self-custody',
});
// withWallet.wallet.address = Solana address
// withWallet.wallet.secret_key = SAVE — cannot be recovered

// Child registration (requires parent credentials)
const child = await register('worker-1', {
  registryUrl: 'https://provenonce.io',
  parentHash: creds.hash,
  parentApiKey: creds.api_key,
});

Quick Start

import { BeatAgent } from '@provenonce/sdk';

const agent = new BeatAgent({
  apiKey: 'pvn_...',
  registryUrl: 'https://provenonce.io',
  verbose: true,
});

await agent.init();           // Birth in Beat time

// Purchase a SIGIL (cryptographic identity)
const sigil = await agent.purchaseSigil({
  identity_class: 'autonomous',
  principal: 'my-agent',
  tier: 'ind',
  payment_tx: 'solana-tx-signature...',
});

// Start heartbeating (paid liveness proofs)
agent.startHeartbeat();

// Get your Passport (latest lineage proof)
const passport = await agent.getPassport();
console.log(passport?.identity_class);     // 'autonomous'
console.log(passport?.provenonce_signature); // Ed25519 signed

// Verify any proof offline — no API call needed
const valid = BeatAgent.verifyProofLocally(passport, authorityPubKeyHex);

agent.stopHeartbeat();

API

BeatAgent

| Method | Description | |--------|-------------| | init() | Initialize the agent's Beat chain (birth in Logical Time) | | purchaseSigil(opts) | Purchase a SIGIL identity (required for heartbeating) | | updateMetadata(fields) | Update mutable SIGIL metadata fields | | heartbeat(paymentTx?, globalAnchor?) | Submit a paid heartbeat and receive a signed lineage proof | | startHeartbeat() | Start autonomous heartbeat loop | | stopHeartbeat() | Stop heartbeat | | getPassport() | Get latest lineage proof (Passport) | | reissueProof(paymentTx?) | Reissue proof without extending lineage | | requestSpawn(name?) | Spawn a child agent (requires accumulated beats) | | getStatus() | Get full beat status from registry | | getLocalState() | Get local state (no network call) | | static verifyProofLocally(proof, pubKey) | Verify a lineage proof offline |

BeatAgentConfig

| Option | Default | Description | |--------|---------|-------------| | apiKey | required | API key from registration (pvn_...) | | registryUrl | required | Provenonce registry URL | | heartbeatIntervalSec | 300 | Seconds between automatic heartbeats | | onHeartbeat | — | Callback when heartbeat completes | | onError | — | Callback on error | | onStatusChange | — | Callback when status changes | | verbose | false | Enable console logging |

register(name, options)

| Option | Description | |--------|-------------| | registryUrl | Registry URL (required) | | registrationSecret | Registration gate (mainnet) | | walletModel | 'self-custody' or 'operator' (opt-in wallet) | | walletChain | 'solana' or 'ethereum' | | walletAddress | Ethereum BYO address | | walletSignFn | Signing function for BYO wallets | | parentHash | Parent hash (child registration) | | parentApiKey | Parent's API key (child registration) |

Returns RegistrationResult with hash, api_key, secret, wallet?.

Note: Agent names should only contain [a-zA-Z0-9_\-. ]. Other characters are stripped by the server before signature verification.

Phase 2 Types

import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';

// Passport = LineageProof (type alias)
// Contains: agent_hash, agent_public_key, identity_class, lineage_chain_hash,
//           provenonce_signature, issued_at, valid_until, etc.

// IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator'

purchaseSigil(opts) required fields

await agent.purchaseSigil({
  identity_class: 'narrow_task' | 'autonomous' | 'orchestrator',
  principal: 'my-agent',
  tier: 'sov' | 'org' | 'ind' | 'eph' | 'sbx',
  payment_tx: 'solana-tx-signature...', // or 'devnet-skip' on devnet
  name: 'optional-display-name'
});

Error Handling

import { ProvenonceError, AuthError, RateLimitError, FrozenError, ErrorCode } from '@provenonce/sdk';

try {
  await agent.heartbeat();
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfterMs}ms`);
  } else if (err instanceof FrozenError) {
    console.log('Agent is frozen — heartbeat refused');
  } else if (err instanceof AuthError) {
    console.log('Invalid API key');
  }
}

Framework Integration Examples

Ready-to-run examples for popular agent frameworks are in examples/:

| Framework | File | What it shows | |-----------|------|---------------| | CrewAI | crewai_example.py | Register a research crew with parent-child lineage | | AutoGen | autogen_example.py | Coder + reviewer agents with post-run provenance audit | | LangGraph | langgraph_example.py | Pipeline nodes with on-chain audit trail | | Any (Node.js) | add-provenonce.ts | 20-line generic integration |

Python examples use the REST API directly — no Python SDK needed. See examples/README.md for details.

Links

• Live prototype
• npm package
• API docs
• Whitepaper