@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

// Operator wallet registration (Solana — bring your own wallet)
const withWallet = await register('my-org', {
  registryUrl: 'https://provenonce.io',
  walletModel: 'operator',
  walletAddress: '<your-solana-address>',
  walletSignFn: (msg) => signWithYourWallet(msg),
});

// 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';
import { Connection, Keypair, SystemProgram, Transaction, PublicKey } from '@solana/web3.js';

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

await agent.init();           // Initialize beat chain (birth in Logical Time)

// Purchase a SIGIL (cryptographic identity — required before heartbeating)
// Step 1: Send SOL to the ops wallet, get the tx signature
const sigilTx = await sendPayment(0.05); // see "Payment Flow" below
const sigil = await agent.purchaseSigil({
  identity_class: 'autonomous',
  principal: 'my-agent',
  tier: 'ind',
  payment_tx: sigilTx,
});

// Start heartbeating (paid liveness proofs)
// The callback must return a finalized Solana tx signature each interval
agent.startHeartbeat(async () => {
  return await sendPayment(0.0005); // heartbeat fee (tier 1)
});

// Submit VDF beats (free — extends your lifetime beat count)
const beats = await agent.submitBeats(100);
console.log(beats.total_beats);

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

agent.stopHeartbeat();

Payment Flow

Provenonce verifies that the payment sender matches the agent's registered wallet. Use any Solana library to send SOL to the ops wallet address:

// Get the ops wallet address and fee schedule
const fees = await fetch('https://provenonce.io/api/v1/fees/summary').then(r => r.json());
const opsWallet = new PublicKey(fees.payment_address);

// Send payment (example using @solana/web3.js)
async function sendPayment(solAmount: number): Promise<string> {
  const connection = new Connection('https://api.devnet.solana.com', 'finalized');
  const lamports = Math.round(solAmount * 1e9);
  const tx = new Transaction().add(
    SystemProgram.transfer({ fromPubkey: yourWallet.publicKey, toPubkey: opsWallet, lamports }),
  );
  const sig = await connection.sendTransaction(tx, [yourWallet]);
  // Wait for finalization before passing to Provenonce
  await connection.confirmTransaction(sig, 'finalized');
  return sig;
}

Beats vs Heartbeats

Two distinct systems — don't confuse them:

• Beats (submitBeats()) — Free VDF computation. Extends your persistent beat chain, credits "Lifetime Beats". Used for spawn eligibility.
• Heartbeats (heartbeat()) — Paid liveness proof. Requires SIGIL + SOL payment. Proves your agent is alive. Updates heartbeat_count_epoch.

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 passport
startHeartbeat(paymentTxFn)	Start autonomous heartbeat loop
stopHeartbeat()	Stop heartbeat
getPassport()	Get latest passport (cached, no network call)
getLatestPassport()	Get latest passport (alias for getPassport)
reissuePassport(paymentTx?)	Reissue passport 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)
submitBeats(count?)	Submit VDF beats to extend lifetime beat count (free)
static verifyPassportLocally(proof, pubKey)	Verify a passport 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	'operator' (opt-in BYO 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, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';

// Passport is the primary type. LineageProof is a deprecated alias (sunset 2026-09-01).
// 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...',
  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