Library mode

For agents you build yourself in TypeScript or JavaScript — autonomous bots, trading agents, ElizaOS characters, Solana Agent Kit flows — import the SDK and call voight.log() directly. Library mode is provider-agnostic — wrap any LLM call (OpenAI / Anthropic / GLM / Mistral / your-own-proxy) and emit the event yourself. The backend MODEL_PRICING table ships entries for the major providers, so cost / token attribution lights up automatically as long as you set model on the event.

Install

npm install @voightxyz/sdk

Requirements:

Node.js 18+ (uses global fetch)
Bun, Deno, browsers, and Cloudflare Workers all supported

Quick start

import { Voight } from '@voightxyz/sdk'

const voight = new Voight({
  agentId: 'trading-bot.sol',     // SNS domain recommended for autonomous agents
  apiKey: process.env.VOIGHT_KEY, // from voight.xyz/dashboard
})

await voight.log({
  reasoning: 'SOL/USDC spread 8bps — arb window open',
  toolExecuted: 'jupiter.swap',
  transaction: '4zK…9Fp',
  amount: { token: 'SOL', value: 1.5 },
  outcome: 'success',
})

Returns { ok: true, eventId, agentId } on success, { ok: false, error: { code, message } } on failure.

Constructor options

Option	Type	Default	Purpose
`agentId`	string	—	Your agent’s stable identifier. Recommend a SNS domain for autonomous bots (`trading-bot.sol`), a stable label for services (`market-watcher`).
`apiKey`	string	—	From the dashboard. Required for ingestion.
`endpoint`	string	`https://api.voight.xyz`	Override for self-hosted deployments.
`defaults`	object	`{}`	Metadata merged into every event (e.g. `{ env: 'prod', region: 'us-east' }`).
`swallowErrors`	boolean	`true`	When true, `voight.log()` never throws — failures return `{ ok: false }`. Recommended for production.
`fetch`	function	`globalThis.fetch`	Inject a custom fetch (for tests, older runtimes).
`privacyLevel`	`'minimal' \| 'standard' \| 'full'`	`'full'`	For library mode, defaults to Full. Pass `'standard'` to get local PII scrubbing.

The `log()` method

interface LogInput {
  type?: 'reasoning' | 'tool' | 'tx' | 'decision' | 'action' | 'error'
  input?: { prompt?: string; context?: Record<string, unknown> }
  reasoning?: string
  toolsConsidered?: string[]
  toolExecuted?: string
  transaction?: string         // Solana tx signature
  amount?: { token: string; value: number }
  outcome?: 'pending' | 'success' | 'failed'
  durationMs?: number
  errorMessage?: string
  model?: string
  tokens?: { input?: number; output?: number; total?: number }
  metadata?: Record<string, unknown>  // anything custom
  timestamp?: string | number  // ISO string or unix ms
}

All fields optional. The server normalises and defaults type: 'decision' if you don’t pass one. Retry behaviour:

3 attempts by default
Exponential backoff
Respects Retry-After header on 429s
Swallowed by default (swallowErrors: true) — recommended for production agents that shouldn’t crash on observability failures

Examples

Trading bot

const voight = new Voight({
  agentId: 'arbitrage.sol',
  apiKey: process.env.VOIGHT_KEY,
  defaults: { strategy: 'mean-reversion', env: 'prod' },
})

// 1. Reasoning step
await voight.log({
  type: 'reasoning',
  reasoning: `SOL/USDC spread at ${spreadBps}bps, threshold ${thresholdBps}bps — open arb`,
})

// 2. Tool / tx
await voight.log({
  type: 'tx',
  toolExecuted: 'jupiter.swap',
  transaction: txSignature,
  amount: { token: 'SOL', value: 1.5 },
  outcome: 'success',
})

// 3. Error
try {
  await maybeFlakyOperation()
} catch (err) {
  await voight.log({
    type: 'error',
    outcome: 'failed',
    errorMessage: (err as Error).message,
  })
}

ElizaOS character (skill plugin)

// Until @voightxyz/eliza-skill ships, you can wire it manually:
import { Voight } from '@voightxyz/sdk'

const voight = new Voight({
  agentId: 'eliza-research-bot',
  apiKey: process.env.VOIGHT_KEY,
})

agent.on('beforeAction', async (action) => {
  await voight.log({ type: 'action', toolsConsidered: [action.name] })
})

agent.on('afterAction', async (action, result) => {
  await voight.log({
    type: 'action',
    toolExecuted: action.name,
    outcome: result.ok ? 'success' : 'failed',
    durationMs: result.elapsed,
  })
})

A native ElizaOS plugin (@voightxyz/eliza-skill) is on the roadmap and will simplify this to one line.

LangChain / LangGraph agent

import { Voight } from '@voightxyz/sdk'

const voight = new Voight({ agentId: 'lc-agent', apiKey: process.env.VOIGHT_KEY })

const callbacks = [{
  handleToolStart: async (tool, input) => {
    await voight.log({ type: 'action', toolsConsidered: [tool.name] })
  },
  handleToolEnd: async (output) => {
    await voight.log({ type: 'action', outcome: 'success' })
  },
  handleLLMEnd: async ({ generations, llmOutput }) => {
    await voight.log({
      type: 'reasoning',
      reasoning: generations[0]?.[0]?.text,
      tokens: {
        input: llmOutput?.tokenUsage?.promptTokens,
        output: llmOutput?.tokenUsage?.completionTokens,
      },
    })
  },
}]

Error types

type VoightError =
  | { code: 'invalid_payload'; message: string }   // your payload failed Zod validation
  | { code: 'unauthorized'; message: string }      // bad API key
  | { code: 'rate_limited'; message: string }      // 429
  | { code: 'network'; message: string }           // fetch failed
  | { code: 'server'; message: string }            // 5xx
  | { code: 'unknown'; message: string }

When swallowErrors: false, these throw. Otherwise they return as { ok: false, error }.

Privacy in library mode

By default, library callers send events as Full (no scrubbing). To opt into Standard scrubbing per-event:

import { Voight, scrubPii } from '@voightxyz/sdk'

// Manual scrubbing
await voight.log({
  reasoning: scrubPii(`API call with token ${apiKey}`),
})

// Or set a privacy level at construction time and let the SDK handle it
const voight = new Voight({
  agentId: 'my-bot',
  apiKey: process.env.VOIGHT_KEY,
  privacyLevel: 'standard',  // applies scrubPii to every event automatically
})

The same 12 PII patterns + Luhn-validated card detection apply. See the PII patterns reference.

`check()` and `enforce()` — v1.0

const decision = await voight.check({ action: 'swap', context: { amount: 50 } })
if (!decision.allow) return // blocked by policy

Today these return { allow: true, reason: 'not-implemented' } so you can instrument call sites now and flip a flag later. Real implementation ships in v1.0.

HTTP API — for runtimes that don’t use npm at all
POST /v1/events — full HTTP API schema for event ingestion

Getting started

Concepts

AI Apps

Python

Integrations

Install paths

Reference

Resources

Install

Quick start

Constructor options

The `log()` method

Examples

Trading bot

ElizaOS character (skill plugin)

LangChain / LangGraph agent

Error types

Privacy in library mode

`check()` and `enforce()` — v1.0

Next

​Install

​Quick start

​Constructor options

​The log() method

​Examples

​Trading bot

​ElizaOS character (skill plugin)

​LangChain / LangGraph agent

​Error types

​Privacy in library mode

​check() and enforce() — v1.0

​Next

Install

Quick start

Constructor options

The `log()` method

Examples

Trading bot

ElizaOS character (skill plugin)

LangChain / LangGraph agent

Error types

Privacy in library mode

`check()` and `enforce()` — v1.0

Next