Skip to Content
Devnet Preview: data may reset, no production guarantees.
SDK ReferenceBeatAgent

BeatAgent

The main SDK class for managing an agent’s lifecycle: identity, heartbeat, sigils, and passports.

import { BeatAgent } from '@provenonce/sdk';
 
const agent = new BeatAgent({
  apiKey: 'pvn_...',
  registryUrl: 'https://provenonce.io',
  heartbeatIntervalSec: 300,
  verbose: true,
});

Config

PropertyTypeDefaultDescription
apiKeystringrequiredAPI key (pvn_...)
registryUrlstringrequiredRegistry URL
heartbeatIntervalSecnumber300Heartbeat interval in seconds
verbosebooleanfalseEnable logging
onHeartbeatfunctionno-opCalled after each heartbeat
onErrorfunctionno-opCalled on errors
onStatusChangefunctionno-opCalled on status changes

Methods

Runtime signatures (v0.14.0+)

agent.purchaseSigil({
  identity_class: 'narrow_task' | 'autonomous' | 'orchestrator',
  principal: string,
  tier: 'sov' | 'org' | 'ind' | 'eph' | 'sbx',
  payment_tx: string,
  name?: string
});
 
agent.heartbeat(paymentTx: string, globalAnchor?: number);
agent.reissuePassport(paymentTx: string);
BeatAgent.verifyPassportLocally(passport, authorityPubKeyHex, currentBeat?);

init() — Initialize beat chain

Creates the agent’s genesis beat on the registry. Call once before other methods.

const result = await agent.init();
// { ok: true, genesis: '0x...' }

purchaseSigil(opts) — Acquire identity tier

Purchase a SIGIL identity tier. Determines the agent’s privilege level and fee schedule.

const result = await agent.purchaseSigil({
  identity_class: 'autonomous',
  principal: 'my-agent',
  tier: 'ind',
  payment_tx: '5xYzAbCd...', // Solana transaction signature
});
// {
//   ok: true,
//   sigil: { identity_class: 'autonomous', issued_at: '...', tx_signature: '...' },
//   passport: { format_version: 1, agent_hash, ... },
//   fee: { amount_sol, amount_lamports, ... },
// }

Identity classes: narrow_task, autonomous, orchestrator.

heartbeat(paymentTx, globalAnchor?) — Submit proof of liveness

A single call that proves liveness via payment and returns a signed Passport.

const result = await agent.heartbeat('5xYzAbCd...');
// {
//   ok: true,
//   passport: { format_version: 1, agent_hash, ..., provenonce_signature },
//   heartbeat_count_epoch: 42,
//   fee: { amount_sol: 0.0005 },
// }

With explicit global anchor:

const result = await agent.heartbeat('5xYzAbCd...', 11450);

reissuePassport(paymentTx) — Reissue Passport

Request a fresh Passport without advancing the heartbeat counter. Useful when the previous proof has expired (24h validity).

const result = await agent.reissuePassport('5xYzAbCd...');
// { ok: true, passport?: Passport, error?: string }
if (result.passport) {
  console.log(`Valid until: ${new Date(result.passport.valid_until).toISOString()}`);
}

getPassport() / getLatestPassport() — Get cached passport (no network)

Returns the most recent Passport from memory.

const passport = agent.getPassport();
// Passport | null
 
// Or:
const passport = agent.getLatestPassport();
// Passport | null

startHeartbeat(paymentTxFn) / stopHeartbeat() — Autonomous loop

Calls heartbeat() on the configured interval (heartbeatIntervalSec).

agent.startHeartbeat(() => getPaymentTxSignature());  // Begins periodic heartbeat
agent.stopHeartbeat();    // Stops the loop

paymentTxFn is a function that returns a Solana transaction signature string (or a Promise). Called before each heartbeat.

requestSpawnWithBeatsProof(opts?) — Get spawn authorization (recommended)

Automates 5 of the 7 spawn steps: probes for cost, fetches the current anchor, computes VDF beats, submits work-proof to the Beats service for a signed receipt, and gets spawn authorization. The caller must then register the child and finalize.

// Step 1: Get spawn authorization
const result = await agent.requestSpawnWithBeatsProof({
  childName: 'child-agent',   // optional — auto-generated if omitted
  beatsNeeded: 1000,           // optional — probed from server if omitted
});
// {
//   ok: true,
//   spawn_authorization: 'token...',
//   eligible: true,
//   receipt_based: true,
// }
 
// Step 2: Register the child (POST /api/v1/register with spawn_authorization)
// Step 3: Finalize via agent.requestSpawn(childName, childHash)

After registration, the child can heartbeat immediately — no SIGIL required for child agents (depth > 0). See the full walkthrough for the complete 3-step example.

Spawn cost scales with depth and sibling count: floor(floor(1000 × 1.5^depth) × 1.2^siblings) beats.

requestSpawn(childName, childHash) — Spawn (low-level)

Low-level spawn finalization. Use requestSpawnWithBeatsProof() instead unless you need manual control over the Beats proof flow.

const result = await agent.requestSpawn('child-agent', '0x...');
// { ok: true, eligible: true, child_hash: '0x...' }

getStatus() — Fetch agent status from registry

const status = await agent.getStatus();
// {
//   already_initialized: true,
//   total_beats: 1000,
//   genesis_hash: '0x...',
//   status: 'active',
//   difficulty: 1000,
// }

Static Methods

BeatAgent.verifyPassportLocally(passport, authorityPubKeyHex, currentBeat?)

Verify a Passport offline using the registry’s Ed25519 public key. No network call required.

Returns a VerificationResult object (not a boolean):

import { BeatAgent } from '@provenonce/sdk';
 
const result = BeatAgent.verifyPassportLocally(passport, '02ab3f...', currentBeat);
// {
//   valid: boolean,           // true if signature valid AND not expired
//   signatureValid: boolean,  // Ed25519 signature check
//   expired: boolean,         // past valid_until
//   lastHeartbeatBeat: number,
//   beatsSinceHeartbeat: number | null,  // null if currentBeat not provided
//   warning?: string,
// }
 
if (result.valid) {
  console.log('Passport verified');
}

The authority public key is available at GET /api/v1/.well-known/authority-key.

Last updated on
POST /agent/checkin (Deprecated)register()