@silvanexum/sdk

@silvanexum/sdk

Official TypeScript/JavaScript SDK for Silvanexum — the spend-control plane for AI agents. Meter, attribute, cap, and audit what every agent spends across your whole agent-to-agent mesh, on any model or rail. Types are generated from the API's Zod contracts, so they never drift from the live API.

📚 Full docs: https://docs.silvanexum.com

Install

npm install @silvanexum/sdk
# pnpm add @silvanexum/sdk · yarn add @silvanexum/sdk · bun add @silvanexum/sdk

Requires Node ≥ 20 (uses the built-in fetch). Ships dual ESM + CJS with bundled types.

Quickstart — cap spend, then see who spent it

import { Silvanexum } from "@silvanexum/sdk";

const sx = new Silvanexum({ apiKey: process.env.SILVANEXUM_API_KEY });

// Cap runaway spend — a run or mesh hop that would breach the budget is
// rejected server-side (HTTP 402). "Spent" is computed from real run telemetry.
await sx.budgets.create({
  name: "support-team",
  scopeType: "agent",
  scopeId: "agt_123",
  periodType: "monthly",
  limitCredits: 50_000,
  enforcement: "block",
});

// Attribute cost across the mesh — which agent / project / model actually spent.
const rows = await sx.spending.summary({ groupBy: "agent" });
console.table(rows);

Zero-code capture (gateway)

Point your OpenAI client's baseURL at the gateway and use your Silvanexum key. Every call is metered on your own provider key and counts toward budgets — with no change to your agent code:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: sx.gateway.openaiBaseUrl(),
  apiKey: process.env.SILVANEXUM_API_KEY,
  // pass a trace id to stitch a call into a multi-hop mesh graph:
  defaultHeaders: { "x-silvanexum-trace": traceId },
});

What's in the SDK

Resource	What it does
sx.spending	Cost attribution — summary / trends / meshTrace (by agent, project, model, provider)
sx.budgets	Spend caps with off / alert / block enforcement + live status
sx.gateway	Zero-code OpenAI-compatible capture + usage
sx.fleet	Cost, latency, drift, and alert observability
sx.runs · sx.agents	Run agents; read signed, replayable traces
sx.security	Hash-chained audit log + compliance export

…plus marketplace, wallet, routing, connectors, team, and more. Full reference: https://docs.silvanexum.com/docs/sdk-reference/typescript.

Errors

Every failure throws a typed SilvanexumError subclass:

import { RateLimitError, InsufficientCreditsError } from "@silvanexum/sdk";

try {
  await sx.runs.create({ agentId: "agt_123", prompt: "…" });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // budget/credits exhausted (HTTP 402) — top up or raise the cap
  } else if (err instanceof RateLimitError) {
    // the client already retried with backoff; surface to the user
  }
}

Configuration

new Silvanexum({
  apiKey: "sx_live_...",        // or env SILVANEXUM_API_KEY
  baseUrl: "https://api.silvanexum.com", // or env SILVANEXUM_BASE_URL
  timeoutMs: 60_000,
  maxRetries: 2,                // retries 429 / 5xx / connection errors
});

Licensed Apache-2.0.