VaultGraph SDK

VaultGraph is a platform for building trustworthy AI agent applications.

What this SDK is for

- Build canonical JobReceipt payloads that match the portal ingestion API.
- Hash sensitive context before it leaves your system.
- Sign receipts with your vendor keys and submit them to /api/receipts using your vendor API key.
- Verify signatures locally when needed.

Prerequisites

- A VaultGraph vendor organization in the portal (create or join at https://app.vaultgraph.com).
- Vendor API key created in the portal (Org Settings → API Keys). Keep this server-side only.
- At least one agent and consumer defined in the portal so you can reference their IDs when creating receipts.

If you need step-by-step UI guidance, see the VaultGraph Docs.

Install

``bash
pnpm add @vaultgraph/sdk
`

Usage

$3

Supported algorithm: Ed25519. The ingestion API verifies with algorithm: null, which assumes Ed25519/Ed448; RSA/ECDSA signatures are not accepted right now.

`ts
import { generateKeyPair } from "@vaultgraph/sdk";

const { privateKey, publicKey } = generateKeyPair();

console.log("Private key (keep secret):\n", privateKey);
console.log("Public key (share with VaultGraph):\n", publicKey);
`

This helper is server-only (Node 18+/edge) and returns PEM-encoded Ed25519 keys. Store the private key in your secrets manager; never ship it to the browser. Publish the public key wherever you manage org settings or bundle it with exports.

$3

`ts
import {
createReceipt,
hashContext,
signReceipt,
submitReceipt,
verifyReceipt,
} from "@vaultgraph/sdk";

// 1) Hash any sensitive context before sending
const contextHash = hashContext({ transcript: "..." });

// 2) Build the canonical receipt payload
const receipt = createReceipt({
agentId: "agent-123",
consumerId: "consumer-456",
jobId: "job-789",
resolution: "resolved",
contextHash,
metadata: { channel: "email" },
});

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

// 4) Optionally verify locally
const ok = verifyReceipt({
receipt,
signature,
publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
});

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

$3

`ts
import { submitSignedReceipt } from "@vaultgraph/sdk";

const { receipt, signature, 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-123",
consumerId: "consumer-456",
jobId: "job-789",
resolution: "resolved",
contextHash: hashContext({ transcript: "hello" }),
metadata: { source: "sdk" },
});

console.log(response); // { id, status }
`

$3

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

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

$3

`ts
import { createAgentsClient } from "@vaultgraph/sdk";

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

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

const list = await agents.list();
const detail = await agents.get(created.id);

const updated = await agents.update(created.id, {
name: "Support Bot v2",
description: "Now with escalation scoring.",
});

await agents.delete(updated.id);
`

$3

`ts
import { createConsumersClient } from "@vaultgraph/sdk";

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

const created = await consumers.create({
name: "Acme Holdings",
description: "Primary customer record.",
});

const list = await consumers.list();
const detail = await consumers.get(created.id);

const updated = await consumers.update(created.id, {
name: "Acme Holdings v2",
description: "Updated customer record.",
});

await consumers.delete(updated.id);
`

API surface

- hashContext(value, options?) → sha256 hash of canonical JSON/bytes
- createReceipt(input) → normalized JobReceipt
- serializeReceipt(receipt) → canonical JSON string
- signReceipt(options) → signature string (base64 default)
- verifyReceipt(options) → boolean
- createSignedReceipt(options) → { receipt, signature }
- submitSignedReceipt(options) → creates, signs, and submits; defaults apiUrl to portal base
- submitReceipt(options) → POSTs to /api/receipts (requires apiKey)
- createAgentsClient(options) → CRUD helper for /api/agents
- createConsumersClient(options) → CRUD helper for /api/consumers
- generateKeyPair() → returns PEM-encoded Ed25519 keypair
- Types: CreateReceiptInput, JobReceipt, JobReceiptV0, JobResolution, ReceiptVersion, SubmitReceiptOptions, SubmitReceiptResponse, AgentRecord, AgentCreateInput, AgentUpdateInput, AgentsClientOptions, AgentsClient, ConsumerRecord, ConsumerCreateInput, ConsumerUpdateInput, ConsumersClientOptions, ConsumersClient

Notes

- Do not send raw conversation context; send context_hash instead.
- Keep your private key and vendor API key server-side only (API key is required for ingestion).
- Receipt versioning currently v0`; breaking changes will bump the major version of this package.
- Portal: https://app.vaultgraph.com
- Docs: https://vaultgraph.com/docs