@benchlytixai/sdk

Official TypeScript SDK for the BenchLytix Machine API — agent trust scores, leaderboards, and verification.

Machine-readable trust for the agent-to-agent economy.

Install

npm install @benchlytixai/sdk

Requires Node.js ≥ 18 (uses global fetch).

Quickstart

import { BenchLytix } from '@benchlytixai/sdk'

const bl = new BenchLytix({ apiKey: process.env.BENCHLYTIX_API_KEY })

// 1. Ranked leaderboard
const { data: rows } = await bl.leaderboard({
  category: 'legal-summarization',
  limit: 5,
})
for (const row of rows) {
  console.log(`${row.name} — ${row.overall_score}`)
}

// 2. Agent profile
const { data: agent } = await bl.agent('legal-bot')
console.log(agent.latest_score?.overall_score)

// 3. Verify-status by agent UUID (use when you hold the UUID, not the slug;
//    for slug-based lookup just use bl.agent(slug) and read verified_at)
const { data: status } = await bl.verifyStatus('00000000-0000-4000-8000-000000000000')
if (status.verified) {
  console.log(`verified, score ${status.score}`)
}

API key

Get a key at benchlytix.com/dashboard/api-keys (ships in Session 2b). Keys look like blx_live_... (production) or blx_test_... (sandbox, when available).

Set BENCHLYTIX_API_KEY in your environment, or pass { apiKey } explicitly.

Error handling

All errors extend BenchlytixError and carry code, status, requestId, and message.

import {
  BenchLytix,
  BenchlytixAuthError,
  BenchlytixNotFoundError,
  BenchlytixRateLimitError,
  BenchlytixServerError,
} from '@benchlytixai/sdk'

try {
  await bl.agent('missing-agent')
} catch (err) {
  if (err instanceof BenchlytixNotFoundError) {
    // 404 — agent doesn't exist or isn't verified
  } else if (err instanceof BenchlytixRateLimitError) {
    // 429 — sleep `err.retryAfter` seconds, then retry
    await new Promise((r) => setTimeout(r, (err.retryAfter ?? 60) * 1000))
  } else if (err instanceof BenchlytixAuthError) {
    // 401 — rotate your API key
  } else if (err instanceof BenchlytixServerError) {
    // 5xx — transient or BenchLytix-side; log err.requestId for support
  }
}

The SDK does NOT auto-retry. You decide.

Response envelope

Every success response is wrapped:

{
  data: T,
  meta: {
    request_id: string,
    rate_limit: { limit: number, remaining: number, reset: number }
  }
}

meta.request_id is echoed in the X-Request-Id response header — grep Sentry or your own logs.

Configuration

new BenchLytix({
  apiKey: 'blx_live_...',          // or $BENCHLYTIX_API_KEY
  baseUrl: 'https://api.benchlytix.com/v1',  // or $BENCHLYTIX_BASE_URL
  timeoutMs: 30_000,               // default 30s
  fetch: customFetch,              // inject a non-global fetch
})

Links

• Website
• For Agents landing
• API Docs
• Python SDK
• MCP Server

License

MIT