Skip to main content
The official Node.js SDK for VaultGraph — the trust and verification platform for AI agents. Use this SDK to submit signed JobReceipts from your backend, manage agents and consumers via the API, and verify receipt signatures locally.

​
Install

pnpm add @vaultgraph/sdk
Also works with npm install @vaultgraph/sdk or yarn add @vaultgraph/sdk.

​
Prerequisites

  1. Sign up at app.vaultgraph.com and create your organization
  2. Follow Credentials Setup for credentials setup (API key + public/private key pairs).
  3. Register at least one Agent and Consumer in the platform or via the API

​
Quick start

Submit your first signed receipt in under 10 lines: 
import { submitSignedReceipt, hashContext } from "@vaultgraph/sdk";

const { response } = await submitSignedReceipt({
  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
  publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
  privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
  agentId: "agent-uuid",
  consumerId: "consumer-uuid",
  jobId: "job-001",
  resolution: "success",
  contextHash: hashContext({ transcript: "..." }),
  metadata: { channel: "email" },
});

console.log(response); // { id: "receipt-uuid", status: "verified" }
This creates a canonical JobReceipt, signs it with your Ed25519 private key, and submits it to VaultGraph — all in one call. Trust scores update on your vendor dashboard automatically.

​
Step-by-step usage

If you need more control than the one-liner above, you can create, sign, and submit receipts separately: 
import {
  createReceipt,
  hashContext,
  signReceipt,
  verifyReceipt,
  submitReceipt,
} from "@vaultgraph/sdk";

// 1. Hash sensitive context locally (never sent to VaultGraph)
const contextHash = hashContext({ transcript: "..." });

// 2. Build the canonical receipt
const receipt = createReceipt({
  agentId: "agent-uuid",
  consumerId: "consumer-uuid",
  jobId: "job-001",
  resolution: "success",
  contextHash,
  metadata: { channel: "email" },
});

// 3. Sign with your Ed25519 private key
const signature = signReceipt({
  receipt,
  privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
});

// 4. Verify locally (optional — useful for debugging)
const ok = verifyReceipt({
  receipt,
  signature,
  publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
});

// 5. Submit to VaultGraph
await submitReceipt({
  receipt,
  signature,
  publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
});

​
Create + sign without submitting

import { createSignedReceipt } from "@vaultgraph/sdk";

const { receipt, signature } = createSignedReceipt({
  agentId: "agent-uuid",
  consumerId: "consumer-uuid",
  jobId: "job-001",
  resolution: "success",
  contextHash: "abc123",
  privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
  metadata: { channel: "sms" },
});

​
Verify exported receipts

If you export receipts from the platform as JSON, each item includes the canonical receipt payload and its signature. Verify them offline with the vendor’s public key: 
import { verifyReceipt } from "@vaultgraph/sdk";

const publicKey = process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!;

for (const item of exportedReceipts) {
  const valid = verifyReceipt({
    receipt: item.receipt,
    signature: item.signature,
    publicKey,
  });
  console.log(item.receipt.job_id, valid ? "valid" : "INVALID");
}

​
Manage agents

Full CRUD for the /api/agents endpoint, plus trust score queries: 
import { createAgentsClient } from "@vaultgraph/sdk";

const agents = createAgentsClient({
  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
});

// Create
const agent = await agents.create({
  name: "Support Bot",
  description: "Handles tier-1 support workflows.",
});

// List and get
const all = await agents.list();
const detail = await agents.get(agent.id);

// Update
await agents.update(agent.id, { name: "Support Bot v2" });

// Trust scores (1–90 day window)
const scores = await agents.getScores(agent.id, { days: 30 });
console.log(scores.trust_score); // e.g., 0.92
console.log(scores.daily_scores); // [{ date, trust_score, receipt_count, ... }]

// Delete
await agents.delete(agent.id);

​
Manage consumers

Full CRUD for the /api/consumers endpoint: 
import { createConsumersClient } from "@vaultgraph/sdk";

const consumers = createConsumersClient({
  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
});

const consumer = await consumers.create({
  name: "Acme Holdings",
  description: "Enterprise customer.",
});

const all = await consumers.list();
const detail = await consumers.get(consumer.id);
await consumers.update(consumer.id, { name: "Acme Corp" });
await consumers.delete(consumer.id);

​
API reference

​
Receipt functions

FunctionDescription
hashContext(value, options?)SHA-256 hash of canonical JSON/bytes
createReceipt(input)Build a normalized JobReceipt
serializeReceipt(receipt)Canonical JSON string of a receipt
signReceipt(options)Sign a receipt (returns base64 signature)
verifyReceipt(options)Verify a receipt signature (returns boolean)
createSignedReceipt(options)Create + sign in one step
submitSignedReceipt(options)Create + sign + submit in one step
submitReceipt(options)POST a signed receipt to /api/receipts
generateKeyPair()Generate PEM-encoded Ed25519 keypair

​
Client factories

FunctionDescription
createAgentsClient(options)CRUD for /api/agents + getScores()
createConsumersClient(options)CRUD for /api/consumers

​
Types

Receipts: CreateReceiptInput, JobReceipt, JobReceiptV0, JobResolution, ReceiptVersion, SubmitReceiptOptions, SubmitReceiptResponse, CreateSignedReceiptOptions, SubmitSignedReceiptOptions Agents: AgentRecord, AgentCreateInput, AgentUpdateInput, AgentScoresSummary, AgentDailyScore, AgentScoresQueryOptions, AgentsClient, AgentsClientOptions Consumers: ConsumerRecord, ConsumerCreateInput, ConsumerUpdateInput, ConsumersClient, ConsumersClientOptions

​
Important notes

  • Never send raw context — always hash it with hashContext() first
  • Server-side only — keep your private key and API key out of browser/client code
  • Receipt version — currently v0; breaking changes will bump the major SDK version
  • Ed25519 only — RSA and ECDSA are not supported for receipt signing