@provenonce/sdk

@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